Develop

.gitignore

@@ -21,3 +21,5 @@ yarn-error.log*
 .pnpm-debug.log*
 
 .env
+
+.atl

AGENTS.md

@@ -0,0 +1,155 @@
+# AGENTS.md — Stakely Docs
+
+This file is the fast context handoff for agents working in this repository. Read it before editing anything.
+
+## Non-negotiable rules
+
+- Use English for repository artifacts: documentation, UI copy, code comments, identifiers, commit messages, and PR text unless the user explicitly asks otherwise.
+- Never add `Co-Authored-By` or AI attribution to commits.
+- Use conventional commits if you create commits.
+- Keep changes focused and minimal. Do not rewrite broad sections unless the user asked for it.
+- Do not edit generated output in `build/` or `.docusaurus/`; edit source files instead.
+- Before finishing any repository change, update both LLM context files in the same change:
+  - `static/llms.txt`
+  - `static/staking-api/llms-full.txt`
+  This is crucial. These files are public AI entry points and must stay synchronized with the docs.
+
+## Project snapshot
+
+Stakely Docs is a Docusaurus static documentation site for multiple Stakely products.
+
+| Area | Purpose |
+| --- | --- |
+| `docs/staking-api/` | Stakely Staking API documentation, network guides, signing guides, endpoints, authentication, supported networks, and AI guide. |
+| `docs/public-nodes/` | Public RPC/LCD/REST/JSON-RPC/Beacon/checkpoint endpoint documentation. |
+| `docs/obol-portal/` | Obol DVT portal documentation and technical architecture. |
+| `docs/simple-csm/` | Simple CSM product documentation. |
+| `src/pages/index.js` | Homepage cards for the main documentation areas. |
+| `src/components/` | Small React components used by pages/docs, including cards, app URL links, OpenAPI link, and Chatwoot widget. |
+| `src/theme/` | Docusaurus theme customization. `Root.jsx` mounts Chatwoot globally. |
+| `src/css/` | Global and component styling. |
+| `static/` | Files copied as-is to public URLs, including AI-readable docs. |
+| `tests/smoke.test.js` | Dependency/API surface smoke tests and major-version guards. |
+| `.github/workflows/build-push-commit.yaml` | Builds and pushes Docker images for `main` and `develop`, then updates deployment manifests. |
+
+## Runtime and commands
+
+- Package manager: `pnpm`.
+- Required Node version: `>=18.0` from `package.json`; Docker uses Node `24-slim`.
+- Install: `pnpm install --frozen-lockfile`.
+- Dev server: `pnpm start`.
+- Production build: `pnpm build`.
+- Smoke tests: `pnpm smoke:test`.
+- Docusaurus clear: `pnpm clear` when cached routes/build state gets stale.
+
+## Docusaurus architecture
+
+- Main config: `docusaurus.config.js`.
+- Docs are served at the site root with `routeBasePath: '/'`.
+- Sidebar config: `sidebars.js`; sidebars are autogenerated per product section.
+- Locale: English only (`en`).
+- Blog is disabled.
+- Mermaid diagrams are enabled.
+- Broken Markdown links throw during build.
+- Search uses `@easyops-cn/docusaurus-search-local`.
+- API reference uses `@scalar/docusaurus` at `/staking-api/api-reference`.
+- The Scalar spec URL defaults to `https://staking-api.stakely.io/openapi.json` and can be overridden by `STAKING_API_DOC_JSON_URL`.
+
+## Environment variables
+
+See `.env-example`.
+
+| Variable | Used for |
+| --- | --- |
+| `STAKING_API_URL` | Staking API docs/backend URL exposed in Docusaurus custom fields. |
+| `STAKING_API_DOC_JSON_URL` | OpenAPI schema URL used by Scalar and `StakingOpenApiLink`. |
+| `APP_URL` | App URL rendered by `AppUrl`. |
+| `CHATWOOT_WEBSITE_TOKEN` | Chatwoot widget token. |
+| `CHATWOOT_BASE_URL` | Chatwoot instance URL. |
+| `CHATWOOT_ENABLED` | Enables Chatwoot only when set to `true`. |
+
+## Documentation conventions
+
+- Documentation content should be concise, practical, and implementation-oriented.
+- Preserve existing Docusaurus front matter and `_category_.json` ordering patterns.
+- For Staking API endpoint pages, keep links to:
+  - Scalar API Docs: `/staking-api/api-reference`
+  - OpenAPI schema: `https://staking-api.stakely.io/openapi.json` unless config requires otherwise.
+- If editing `docs/staking-api/ai-integration-guide.md`, mirror equivalent raw Markdown content in `static/staking-api/ai-integration-guide.md`.
+- If changing supported networks, endpoint behavior, API flows, authentication, signing guidance, or public AI routing, update both LLM files:
+  - `static/llms.txt`
+  - `static/staking-api/llms-full.txt`
+- Even for non-API changes, check whether the public LLM files need updated routing or context before finishing. Do not skip this check.
+
+## Public AI-readable files
+
+These source files are served directly from `static/`:
+
+| Source file | Public URL |
+| --- | --- |
+| `static/llms.txt` | `https://docs.stakely.io/llms.txt` |
+| `static/staking-api/llms-full.txt` | `https://docs.stakely.io/staking-api/llms-full.txt` |
+| `static/staking-api/ai-integration-guide.md` | `https://docs.stakely.io/staking-api/ai-integration-guide.md` |
+
+`build/llms.txt` and `build/staking-api/llms-full.txt` are generated output. Do not edit them directly.
+
+## Staking API context
+
+The Stakely Staking API is non-custodial. It crafts unsigned staking transactions and exposes staking data; integrators sign transactions with their own wallet, signer, custodian, MPC, hardware wallet, or backend signer.
+
+Key rules for Staking API docs:
+
+- OpenAPI source of truth: `https://staking-api.stakely.io/openapi.json`.
+- Auth header: `X-API-KEY`.
+- Optional network selector: `X-NETWORK`.
+- Never imply users should send private keys, seed phrases, mnemonics, or custody secrets to Stakely.
+- Keep signing under the integrator/user control.
+- Prefer testnet examples when the target network is not specified.
+
+Documented Staking API areas include:
+
+- Cosmos Hub native staking.
+- Ethereum StakeWise.
+- Monad native staking.
+- Monad Magma liquid staking.
+- Pharos native staking.
+- Solana native staking.
+- Sui native staking.
+- Authentication and optional response signature verification.
+- Supported networks and AI integration guidance.
+
+## React/component notes
+
+- `AppUrl` renders `APP_URL` from Docusaurus `customFields` and falls back to a visible `APP_URL` placeholder if unset.
+- `StakingOpenApiLink` renders the configured staking OpenAPI URL.
+- `ChatwootWidget` runs only in the browser and only when all Chatwoot env fields are configured and enabled.
+- `Card` is used by the homepage cards and supports light/dark product icons.
+
+## Testing guidance
+
+Run the smallest useful verification:
+
+- Documentation/content-only changes: usually `pnpm build` is the useful check because Docusaurus catches broken Markdown links.
+- Dependency updates or component import changes: run `pnpm smoke:test`.
+- Config, routing, or plugin changes: run `pnpm build`; add `pnpm smoke:test` when dependency API compatibility is relevant.
+
+Smoke tests intentionally guard dependency API surfaces and major versions for React, Docusaurus, Scalar, local search, Chatwoot integration, and related imports.
+
+## Deployment context
+
+The GitHub workflow builds Docker images for `main` and `develop`, selects environment variables based on the branch, pushes `stakely/stakely-docs:<branch>`, writes the image digest into the `Stakely/kubernetes-manifests` repo, and notifies Discord.
+
+## Agent workflow checklist
+
+Before editing:
+
+1. Check `git status --short` and avoid overwriting user changes.
+2. Identify whether the change affects docs, routes, config, static assets, tests, or deployment.
+3. For broad documentation changes, inspect nearby pages and category files before editing.
+
+Before finishing:
+
+1. Update `static/llms.txt` and `static/staking-api/llms-full.txt` as required for the change.
+2. Run the relevant verification command if feasible.
+3. Check `git diff --check` and review the final diff.
+4. Summarize changed files and any verification not run.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

REVIEW.md

@@ -0,0 +1,63 @@
+# REVIEW.md — Stakely Docs review checklist
+
+Use this checklist in automated or human review pipelines before approving changes to this repository.
+
+## Critical review rule: LLM files must match the docs
+
+Every review must verify that the public AI context files are updated when documentation changes:
+
+- `static/llms.txt`
+- `static/staking-api/llms-full.txt`
+
+If the PR changes documentation, routes, product coverage, API behavior, supported networks, endpoint lists, authentication, signing guidance, AI integration guidance, or public links, the reviewer must compare those changes against both LLM files.
+
+Do not approve the change if the docs and LLM files are out of sync.
+
+## Review path
+
+1. Read `AGENTS.md` first for repository context and non-negotiable rules.
+2. Inspect the changed files with `git diff --stat` and `git diff`.
+3. Check whether the change affects documentation or public AI context.
+4. Verify `static/llms.txt` and `static/staking-api/llms-full.txt` are updated or confirm they genuinely do not need changes.
+5. Run the smallest useful verification command.
+6. Report blockers separately from suggestions.
+
+## LLM sync checklist
+
+For every documentation change, verify:
+
+- [ ] `static/llms.txt` still routes agents to the right product docs and public URLs.
+- [ ] `static/staking-api/llms-full.txt` reflects current Staking API docs, endpoints, networks, signing rules, and security guidance.
+- [ ] New or renamed pages are represented in the LLM files when they are relevant to AI consumers.
+- [ ] Removed or outdated links are also removed from the LLM files.
+- [ ] `build/llms.txt` and `build/staking-api/llms-full.txt` were not edited directly; source files under `static/` are the files to review.
+
+## What to block
+
+Block approval when any of these are true:
+
+- Documentation changed but relevant LLM files were not updated and no clear reason is given.
+- LLM files contradict the documentation.
+- Staking API docs imply users should send private keys, seed phrases, mnemonics, or custody secrets to Stakely.
+- API schemas, endpoint names, headers, or network values are asserted without matching the OpenAPI/source docs.
+- Generated folders such as `build/` or `.docusaurus/` are edited as source.
+- Broken Markdown links, route changes, or Docusaurus config changes are not verified with a build when verification is feasible.
+
+## Review output format
+
+Return a concise review with this shape:
+
+```md
+## Verdict
+Approved | Blocked | Approved with comments
+
+## Required fixes
+- ...
+
+## LLM file sync
+- Checked `static/llms.txt`: yes/no, notes
+- Checked `static/staking-api/llms-full.txt`: yes/no, notes
+
+## Verification
+- Command: result
+```

docs/staking-api/cosmos-hub/native-staking/endpoints.md

@@ -14,7 +14,7 @@ Once you already have access to the Staking API with a validated user and existi
 :::tip
 
 You can check the **Staking API Reference** here:
-- Rendered <a href="/staking-api/api-reference" target="_blank" rel="noopener noreferrer">doc page</a>.
+- <a href="/staking-api/api-reference" target="_blank" rel="noopener noreferrer">Scalar API Docs</a>.
 - <StakingOpenApiLink />
 :::
 

docs/staking-api/ethereum/stakewise/endpoints.md

@@ -14,7 +14,7 @@ Once you already have access to the Staking API with a validated user and existi
 :::tip
 
 You can check the **Staking API Reference** here:
-- Rendered <a href="/staking-api/api-reference" target="_blank" rel="noopener noreferrer">doc page</a>.
+- <a href="/staking-api/api-reference" target="_blank" rel="noopener noreferrer">Scalar API Docs</a>.
 - <StakingOpenApiLink />
 :::
 

docs/staking-api/monad/magma/endpoints.md

@@ -15,7 +15,7 @@ Once you already have access to the Staking API with a validated user and existi
 :::tip
 
 You can check the **Staking API Reference** here:
-- Rendered <a href="/staking-api/api-reference" target="_blank" rel="noopener noreferrer">doc page</a>.
+- <a href="/staking-api/api-reference" target="_blank" rel="noopener noreferrer">Scalar API Docs</a>.
 - <StakingOpenApiLink />
 :::
 

docs/staking-api/monad/native-staking/endpoints.md

@@ -13,7 +13,7 @@ Once you already have access to the Staking API with a validated user and existi
 :::tip
 
 You can check the **Staking API Reference** here:
-- Rendered <a href="/staking-api/api-reference" target="_blank" rel="noopener noreferrer">doc page</a>.
+- <a href="/staking-api/api-reference" target="_blank" rel="noopener noreferrer">Scalar API Docs</a>.
 - <StakingOpenApiLink />
 :::
 

docs/staking-api/pharos/native-staking/endpoints.md

@@ -13,7 +13,7 @@ Once you already have access to the Staking API with a validated user and existi
 :::tip
 
 You can check the **Staking API Reference** here:
-- Rendered <a href="/staking-api/api-reference" target="_blank" rel="noopener noreferrer">doc page</a>.
+- <a href="/staking-api/api-reference" target="_blank" rel="noopener noreferrer">Scalar API Docs</a>.
 - <StakingOpenApiLink />
 :::
 

docs/staking-api/solana/native-staking/endpoints.md

@@ -14,7 +14,7 @@ Once you already have access to the Staking API with a validated user and existi
 :::tip
 
 You can check the **Staking API Reference** here:
-- Rendered <a href="/staking-api/api-reference" target="_blank" rel="noopener noreferrer">doc page</a>.
+- <a href="/staking-api/api-reference" target="_blank" rel="noopener noreferrer">Scalar API Docs</a>.
 - <StakingOpenApiLink />
 :::
 

docs/staking-api/sui/native-staking/endpoints.md

@@ -13,7 +13,7 @@ Once you already have access to the Staking API with a validated user and existi
 :::tip
 
 You can check the **Staking API Reference** here:
-- Rendered <a href="/staking-api/api-reference" target="_blank" rel="noopener noreferrer">doc page</a>.
+- <a href="/staking-api/api-reference" target="_blank" rel="noopener noreferrer">Scalar API Docs</a>.
 - <StakingOpenApiLink />
 :::