> For the complete documentation index, see [llms.txt](https://comunity.gitbook.io/learning.comunitynexus/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://comunity.gitbook.io/learning.comunitynexus/26.2/toolkit-guides/web-sites/extend-a-web-site-with-the-helper-library.md).

# Extend a web site with the helper library

Every web site is created with a helper library that provides documented access to platform login, data, tracing and analytics. The library is not part of the served site. It is development scaffolding, intended to be read by a coding agent so that the agent can build the application without you learning the platform's APIs.

## What the library contains

The library sits under `helper-lib-dist` in the web site repository.

| Item                                              | Purpose                                                                                                                                           |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lib/comunity-platform-api-helpers-<version>.tgz` | The package itself. Framework-neutral JavaScript wrapping the platform's login, data, tracing and analytics endpoints.                            |
| `docs/`                                           | An Open Knowledge Format documentation set covering the API, the concepts behind it, and the supported workflows. Written to be read by an agent. |
| `examples/`                                       | Two runnable example applications, one plain and one React.                                                                                       |
| `AGENTS.md`                                       | The library's own contract, telling an agent how to use the documentation set.                                                                    |
| `README_AGENTS.md`                                | Instructions for making the library discoverable from your project.                                                                               |
| `prompt_examples.md`                              | Two ready-made prompts.                                                                                                                           |

At the root of the repository, `.project.config` holds the `server_url` and `project_name` values that identify the platform installation and project. The library treats these as canonical, and every route the application calls resolves from them.

## Make the library discoverable to your agent

A coding agent opening the repository has no indication the library exists. Making it discoverable is a manual step, and it is required before any of the prompts will work as intended.

1. Open `helper-lib-dist/README_AGENTS.md`.
2. Copy the instruction block it provides, which begins `# Project agent notes`. Copy only that block, not the surrounding guidance.
3. Create a file named `AGENTS.md` at the **root of the repository** and paste the block into it. Where the project already has a root `AGENTS.md`, add the block to the existing file rather than replacing it.

{% hint style="info" %}
Three files have similar names and different jobs. `helper-lib-dist/AGENTS.md` is the library's own contract and is not edited. `helper-lib-dist/README_AGENTS.md` contains the block to copy. The root `AGENTS.md` is the file you create, and it is the only one your agent reads first.
{% endhint %}

Once the root file exists, the agent follows a chain: your root `AGENTS.md` points to the library's `AGENTS.md`, which points to `docs/index.md`, which links to the specific pages a task requires.

**To confirm it is working**, ask the agent what `.project.config` contains and where the helper library documentation is. An agent reading the file answers both without being told where to look.

## Build the application from a prompt

`helper-lib-dist/prompt_examples.md` provides two prompts. Copy one into your agent and let it generate the application.

**Entity browser.** Lists the entities in your project, reads records for the entity a visitor selects, attempts every read without authentication first, and prompts for sign-in only where a read is refused. It does not provide a way to register.

**Web page with login dialog.** Provides sign-in, registration, forgot-password and reset-password dialogs, and a landing page with a personalised greeting and sign-out. A PIN is required only when completing a password reset.

{% hint style="warning" %}
Before running either prompt, set its documentation entry point to `helper-lib-dist/docs/index.md`. The path given in the prompt does not exist in the bundle, and an agent that follows it begins by failing to find its documentation.
{% endhint %}

The prompts are demonstrations of what the library can do, not application templates. Neither produces a site you would publish as it stands, and neither writes data.

## Install and run

The library package is installed from the copy in your repository rather than from a registry:

```bash
npm install
```

How the application is run depends on what the agent generated. The same prompt can produce a bundled application with a development server, or a set of static files served directly. Check the `scripts` section of the generated `package.json` for the command to use.

Check the generated source for the platform address and project name. Where the agent has written these into the code rather than reading them from `.project.config`, the application works only against the environment it was generated in.

## Verify the application

Set one entity readable without authentication and leave the others as they are. See [Web site prerequisites and data access](/learning.comunitynexus/26.2/toolkit-guides/web-sites/web-site-prerequisites-and-data-access.md).

A correctly built application then shows all three outcomes on the same screen:

* the open entity returns its records with no prompt to sign in
* a restricted entity prompts for sign-in at the point its records are requested
* signing in without sufficient permission produces a message distinguishing that from not being signed in

Without that contrast, every entity prompts for sign-in and a working application cannot be told apart from a broken one.

{% hint style="warning" %}
Confirm that the application lists your entities. Where it lists none, the agent has derived the entity list from the wrong part of the metadata response. Supply it with the actual response shape and have it correct the derivation.
{% endhint %}

## Deploy what you have built

The repository and the served site are not synchronised. Committing your work does not change the site. Build the application, then upload the output to the web site as an archive, with the site's default document at the root of the zip.

## Where to go next

* [Manage web site files in the Toolkit](/learning.comunitynexus/26.2/toolkit-guides/web-sites/manage-web-site-files-in-the-toolkit.md): upload the built output to the site