update readme, contributing. add agents

AGENTS.md

@@ -0,0 +1,39 @@
+# AGENTS.md
+
+Review `README.md` and `CONTRIBUTING.md` for all relevant repository information.
+
+## Development Tips
+
+- Use `npm install` to install dependencies.
+- Use `npm run dev` to start the local development server (runs `prebuild` automatically).
+- Use `npm run build` to produce a production build (also runs `prebuild` automatically).
+- Do not edit files in `build/`; it is compiled output.
+- The `scripts/prebuild.js` script must run before the dev server or build — it is wired into `predev`/`prebuild` hooks, so calling `npm run dev` or `npm run build` is sufficient.
+
+## Code Style
+
+- TypeScript (config files and scripts), MDX/Markdown (content).
+- Prettier is configured via `@harperdb/code-guidelines/prettier` (see `package.json`).
+- Format command: `npm run format:write`. Run this after editing any `.ts`, `.md`, or `.mdx` files.
+- The lint script is a no-op (`echo 0`); do not expect `npm run lint` to catch issues.
+
+## Content Structure
+
+- Content lives in four directories: `learn/`, `reference/`, `release-notes/`, and `fabric/`.
+- Sidebar configs: `sidebarsLearn.ts`, `sidebarsReference.ts`, `sidebarsReleaseNotes.ts`, `sidebarsFabric.ts`.
+- Reference is versioned; current version is v5 (`reference/`). Archived v4 content is in `reference_versioned_docs/version-v4/`.
+- Do not modify `reference_versioned_docs/` for current (v5) work; edit `reference/` instead.
+- The `<VersionBadge>` component is globally registered — no import needed in `.md`/`.mdx` files.
+- See the complete repository organization in `CONTRIBUTING.md`
+
+## Testing
+
+- There is no automated test suite. Verification is done by running the dev server or build.
+- `npm run build` is the best end-to-end check — it will fail on broken links, missing imports, or MDX errors.
+- `npm run typecheck` checks TypeScript config files only.
+- Known issue: `npm run serve` (post-build preview) 404s on paths like `/docs/4.X` locally due to an upstream `serve-handler` bug. This is not a real breakage — see CONTRIBUTING.md for details.
+
+## CI
+
+- CI runs `npm run build` and `npm run format:check` on pull requests.
+- If CI fails on formatting, run `npm run format:write` locally and commit the result.

CONTRIBUTING.md

@@ -70,13 +70,7 @@ Learn is non-versioned. All content lives directly in `learn/` organized into ca
 | Version list          | `reference_versions.json`                               |
 | Plugin config         | `docusaurus.config.ts` → plugin id `reference`          |
 
-Reference is versioned by major Harper version. The `reference_versions.json` file lists all archived versions — currently `["current", "v4"]`. The `current` version maps to `v5` (the in-progress next major) and is not published; `v4` is the default displayed version.
-
-To cut a new version snapshot (e.g. when v5 ships), run:
-
-```bash
-node scripts/cut-version.js
-```
+Reference is versioned by major Harper version. The `reference_versions.json` file lists all archived versions — currently `["current", "v4"]`. The `current` version maps to `v5` (the _current_ major).
 
 #### Release Notes
 
@@ -86,7 +80,7 @@ node scripts/cut-version.js
 | Sidebar       | `sidebarsReleaseNotes.ts`                          |
 | Plugin config | `docusaurus.config.ts` → plugin id `release-notes` |
 
-Release notes are non-versioned in the Docusaurus sense — major version organization is handled manually via subdirectories (`v4-tucker/`, `v3-monkey/`, etc.). The sidebar uses `autogenerated` directives so new files are picked up automatically. See the [Release Notes Process](#release-notes-process) section for the full workflow.
+Release notes are non-versioned in the Docusaurus sense — major version organization is handled manually via subdirectories (`v5-lincoln/`, `v4-tucker/`, `v3-monkey/`, etc.). The sidebar uses `autogenerated` directives so new files are picked up automatically. See the [Release Notes Process](#release-notes-process) section for the full workflow.
 
 #### Fabric
 
@@ -135,7 +129,7 @@ Reference sidebar headers use `className: "reference-category-header"` for compa
 
 #### Legacy Section
 
-Deprecated or discouraged features belong in `reference/legacy/` (current) or `reference_versioned_docs/version-v4/legacy/` (v4). Each legacy page should briefly explain what the feature was and direct users to the modern alternative.
+Deprecated or discouraged features belong in `reference/legacy/`. Each legacy page should briefly explain what the feature was and direct users to the modern alternative.
 
 ---
 
@@ -184,20 +178,28 @@ In previous versions of v4, the default was 9925.
 SQL is still supported but discouraged. See [Database](../database/overview.md) for modern alternatives.
 ```
 
-**Configuration option** (inline in a list):
+**Stabilized feature:**
 
 ```mdx
-- `logger.level` — Log level; _Default_: `"info"` (Added in: v4.1.0)
-```
+## Plugin API
 
-For inline config option annotations inside list items, plain text `(Added in: vX.Y.Z)` is fine — using the component mid-sentence is awkward. Reserve `<VersionBadge>` for standalone placement after headings.
+{/* Now stable! */}
 
-If the introduction version is inferred rather than confirmed by release notes, append a note:
+<VersionBadge type="stable" version="v5.0" />
+{/* Was "experimental" */}
+<VersionBadge version="v4.6" />
+
+The Plugin API is the primary way to implement additional functionality in Harper.
+```
+
+**Configuration option** (inline in a list):
 
 ```mdx
-<VersionBadge version="v4.3.0" /> (inferred from version comparison, needs verification)
+- `logger.level` — Log level; _Default_: `"info"` (Added in: v4.1.0)
 ```
 
+For inline config option annotations inside list items, plain text `(Added in: vX.Y.Z)` is fine — using the component mid-sentence is awkward. Reserve `<VersionBadge>` for standalone placement after headings.
+
 ## Known Issues
 
 ### `docusaurus serve` 404s on `/docs/4.X` paths

README.md

@@ -2,7 +2,7 @@
 
 Documentation website for [Harper](https://harper.fast), a fullstack, serverful Node.js application platform.
 
-Powered by [Docusaurus](https://docusaurus.io/).
+Hosted at [docs.harper.fast](https://docs.harper.fast). Powered by [Docusaurus](https://docusaurus.io/).
 
 ## Contributing