docs: add AGENTS.md guide for the Identus docs portal

AGENTS.md

@@ -0,0 +1,86 @@
+# AGENTS.md — Identus Documentation Portal
+
+Identus documentation site built with Docusaurus 3. Yarn-based monorepo that aggregates content from local files and two git submodules.
+
+## Commands
+
+```bash
+yarn install        # Install deps; postinstall hook runs prepare.sh automatically
+yarn start          # Dev server (also runs prepare.sh before starting)
+yarn build          # Production build (prepare.sh → Docusaurus SSG → static site in build/)
+yarn clear          # Clear Docusaurus cache (.docusaurus/)
+yarn serve          # Serve the production build locally
+```
+
+**`prepare.sh` runs `docusaurus clean-api-docs all && docusaurus gen-api-docs all`** — it is invoked automatically by `yarn install` (postinstall) and by `yarn start`/`yarn build`. You do not need to run it manually.
+
+## Content architecture
+
+All documentation content flows into a single Docusaurus instance via three source paths configured in `src/config/constants.ts`:
+
+| Source path | Contents | Origin |
+|---|---|---|
+| `documentation/` | Learn, develop, reference sections | Local (committed in this repo) |
+| `cloud-agent/docs/docusaurus/` | Cloud Agent guides and OpenAPI spec | `cloud-agent/` git submodule |
+| `sdk-ts/docs/` | TypeScript SDK docs (TypeDoc-generated) | `sdk-ts/` git submodule |
+
+Three sidebars (`sidebars.ts`) map to three top-level nav items:
+
+- **Learn** → `learnSidebar` (discovers `learn/` across all content sources)
+- **Developers** → `developersSidebar` (discovers `develop/`)
+- **Reference** → `referenceSidebar` (discovers `reference/`)
+
+Sidebar items are resolved at build time by `src/utils/discovery.ts` — it scans each content source for `sidebar.ts` files or `_category_.json` files and falls back to auto-generated items sorted by `sidebar_position` frontmatter.
+
+## Auto-generated content — do not edit manually
+
+- **`documentation/reference/Cloud Agent API/`** — Generated by `docusaurus-plugin-openapi-docs` from `cloud-agent/cloud-agent/service/api/http/cloud-agent-openapi-spec.yaml`. Regenerated by `prepare.sh`. Any manual edits here are overwritten on the next build.
+- **SDK TypeDoc pages** (`sdk-ts/docs/sdk/`) — Pre-generated by TypeDoc in the `sdk-ts` submodule and committed there; consumed read-only by this repo. (`docusaurus-plugin-typedoc` is a devDependency but is **not** configured in the Docusaurus build pipeline.) A custom `parseFrontMatter` hook in `docusaurus.config.ts` extracts titles from these pages so they render correctly in sidebars. Do not hand-edit these files — regenerate them in the `sdk-ts` submodule instead.
+
+## Submodules
+
+`cloud-agent/` and `sdk-ts/` are git submodules providing their documentation and OpenAPI specs:
+
+```bash
+git submodule init
+git submodule update --remote --recursive
+```
+
+CI updates submodules weekly via `.github/workflows/update-submodules.yml`. When working with submodule content, ensure the submodule is checked out at the correct commit.
+
+## Sidebar & navigation customization
+
+- `sidebars.ts` — Entry point; calls `discoverSidebar()` for each section
+- `src/utils/discovery.ts` — Scans content paths, loads per-directory `sidebar.ts` or `_category_.json`, falls back to auto-generation
+- `src/config/presets.ts` — Multi-doc preset wiring; configures the docs plugin with include globs, the OpenAPI plugin, and `remarkLinkFixer`
+- `src/plugins/remarkLinkFixer.js` — Rewrites legacy markdown links (e.g., old `/home/` paths) to current URLs; rules configured in `presets.ts`
+- `src/config/headerMenu.ts` — Top navbar items
+- `_category_.json` in content dirs — Sets label, position, collapsibility for sidebar categories
+
+## API doc generation (Redocly)
+
+`redocly.yaml` configures Redocly OpenAPI rendering (theme colors, sidebar, code blocks). This controls how the Cloud Agent API reference looks inside the Docusaurus site. The underlying spec file is `cloud-agent/cloud-agent/service/api/http/cloud-agent-openapi-spec.yaml`.
+
+## Build output
+
+`yarn build` produces a static site in `build/` that is deployed to `https://hyperledger-identus.github.io/docs/` via `release-gh-pages.yml`. The site is a static SSG — no server-side rendering.
+
+## CI & quality checks
+
+- **Mega-linter** — Runs on all PRs (`.github/workflows/mega-linter.yml`); applies auto-fixes and creates fix PRs
+- **Linkinator** — Checks broken links on push to main and weekly on Mondays (`.github/workflows/link-check.yml`); config in `.linkinatorrc.json`
+- **GitHub Pages deploy** — `release-gh-pages.yml` builds and deploys on push to main; uses `peaceiris/actions-gh-pages` with `IDENTUS_CI` token
+
+## Key config files
+
+| File | Purpose |
+|---|---|
+| `docusaurus.config.ts` | Docusaurus core config: site metadata, markdown settings, front matter hooks, plugins |
+| `src/config/presets.ts` | Multi-doc preset: content sources, OpenAPI plugin config, remark link fixer rules |
+| `src/config/constants.ts` | Content path constants (`documentation/`, `cloud-agent/docs/docusaurus/`, `sdk-ts/docs/`) |
+| `src/config/headerMenu.ts` | Navbar sidebar associations |
+| `src/utils/discovery.ts` | Auto-discovers sidebar items from content directories |
+| `sidebars.ts` | Sidebar wiring using `discoverSidebar()` |
+| `redocly.yaml` | Redocly OpenAPI rendering theme |
+| `prepare.sh` | Pre-build: cleans and regenerates API docs |
+| `package.json` | Scripts, deps, Yarn 4 config |