Agents

.github/ISSUE_TEMPLATE/skill-feedback.yaml

@@ -0,0 +1,103 @@
+name: Skill feedback / drift report
+description: Report that a morph-doc Skill (or its paired MDX) gave incorrect, stale, or unroutable guidance.
+title: "[skill-drift] <skill-id>: <one-line summary>"
+labels:
+  - skill-drift
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to flag a Skill drift. This template powers the
+        feedback loop for the **Docs-as-SKILL** contract described in
+        [`VISION.md`](https://github.com/morph-l2/morph-doc/blob/main/VISION.md).
+        The doc maintainer triages every `skill-drift` issue.
+
+  - type: input
+    id: skill-id
+    attributes:
+      label: Skill ID
+      description: Directory name under `skills/`, e.g. `morph-contracts`, `morph-js-sdk`. Leave blank if you are reporting an MDX page with no paired Skill.
+      placeholder: morph-contracts
+    validations:
+      required: false
+
+  - type: input
+    id: doc-path
+    attributes:
+      label: Related doc path
+      description: Path relative to repo root, e.g. `docs/build-on-morph/developer-resources/1-contracts.md`. Optional if unknown.
+      placeholder: docs/...
+    validations:
+      required: false
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Drift category
+      description: Pick the best fit; maintainers may relabel during triage.
+      options:
+        - Stale fact (address / chainId / RPC / token changed)
+        - Wrong routing (Skill triggered for unrelated question)
+        - Missing routing (question should match a Skill but did not)
+        - Executable snippet no longer runs
+        - Self-check item failed during real use
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: Describe the prompt, the Skill that fired (if any), and the answer you received.
+      placeholder: |
+        Prompt: "...the user's question..."
+        Skill fired: morph-contracts
+        Answer given: "..."
+        What was wrong: "..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected instead
+      placeholder: |
+        - Expected fact: ...
+        - Source of truth: ...
+    validations:
+      required: true
+
+  - type: input
+    id: source
+    attributes:
+      label: Authoritative source (optional)
+      description: Link or path to the canonical value (chain explorer, source code, JSON registry, etc.).
+      placeholder: https://... or morph-bridge/public/morph-list/src/mainnet/tokenList.json
+    validations:
+      required: false
+
+  - type: dropdown
+    id: agent
+    attributes:
+      label: Agent / IDE where this occurred
+      options:
+        - Cursor
+        - Claude Code
+        - OpenClaw
+        - Windsurf
+        - Codex
+        - Web chat
+        - Other
+        - Not applicable
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Version info, chain (Mainnet / Hoodi), package versions, screenshots, etc.
+    validations:
+      required: false

.gitignore

@@ -26,5 +26,31 @@ yarn-error.log*
 .anima
 data
 build
-scripts
+# scripts
 build
+examples
+.cursor
+.claude
+.openclaw
+
+# __tests__
+# run-tests.mjs
+content
+
+# agent
+skills-plan
+memory
+USER.md
+SOUL.md
+TOOLS.md
+IDENTITY.md
+HEARTBEAT.md
+DREAMS.md
+*.zh.md
+
+# dapp agent
+planning
+research
+
+# skill-creator description optimization (--results-dir); see skills/README.md
+.local

.husky/pre-commit

@@ -0,0 +1,4 @@
+node __tests__/doc-skill-pairing.test.mjs
+node __tests__/morph-doc-skill-inventory.test.mjs
+node __tests__/skills-sidebar.test.mjs
+npm run build

AGENTS.md

@@ -0,0 +1,121 @@
+# AGENTS.md
+
+Operating instructions for AI agents working in this repository. Loaded by **OpenClaw** when this directory is the agent workspace; use as the shared team handbook for other coding agents too.
+
+**Claude Code** also reads [`CLAUDE.md`](./CLAUDE.md) at session start—project facts below are canonical for any tool.
+
+## Project overview
+
+This is the Morph Documentation website (Docusaurus 3.1.1). Morph is an optimistic zkEVM scaling solution for Ethereum. The site provides developer resources, guides, and API references for the Morph network.
+
+## Knowledge base layout
+
+- **Vision (docs-as-SKILL, external brain, toolchain):** [`VISION.md`](./VISION.md) — write and review MDX/SKILL pairs against this contract so models can instantiate behavior reliably.
+- **Human-readable docs:** `docs/` (MDX). Prefer linking to the authoritative page instead of duplicating long specs in chat.
+- **Executable topic summaries:** `skills/<skill-id>/SKILL.md` (see [`skills/README.md`](./skills/README.md)). Use these for routing and concise procedures.
+- **Agent sub-definition:** `agents/*.md` (also published under `/agents/` on the doc site; navbar **Agents**). Start with [`agents/morph-doc-agent.md`](./agents/morph-doc-agent.md) for skill authoring from a single goal. Canonical skill path is **`skills/<skill-id>/`** at repo root; see [`skills/README.md`](./skills/README.md) to symlink into Cursor / Claude Code / OpenClaw global dirs. When in doubt, treat `docs/` + `skills/` as the product source of truth.
+
+### Three-layer model (knowledge base, brain, connector)
+
+Use morph-doc as Morph’s **versioned knowledge base** and **external brain** for agents. Three layers:
+
+| Layer | Role | In this repo |
+|-------|------|----------------|
+| **Knowledge base** | Canonical facts, long-form narrative, tables, demos (humans + search) | `docs/**/*.mdx` |
+| **Brain** | Reliable behavior: stepwise playbooks, self-checks; authority in Git, not chat memory alone | `skills/<skill-id>/SKILL.md`, plus `__tests__/` where behavior must stay tied to docs |
+| **Connector** | Routes intent to the right surface: YAML `name` / `description` (tool routing), optional MDX `doc_skill_id` (page–skill pairing), **Related Skills** for handoffs without copying sibling bodies | Same `SKILL.md` files; pairing and policy in [`VISION.md`](./VISION.md); symlink and trigger tuning in [`skills/README.md`](./skills/README.md) |
+
+**Connector contract:** Skills do not duplicate full MDX. They connect prompts → **Execution Steps** → pointers into `docs/` → optional sibling skill links.
+
+**Mnemonic:** write facts in `docs/`; write how to be found and executed in `skills/`; keep pairing testable (`doc_skill_id`, `npm test`).
+
+## Development commands
+
+### Local development
+
+- `npm start` or `docusaurus start` — dev server
+- `npm run build` — production build
+- `npm run serve` — serve built site (port 8080)
+- `npm run clear` — clear Docusaurus cache
+- `npm run swizzle` — customize Docusaurus components
+
+### Environment
+
+- `MORPH_DOCS_URL` — site URL when needed
+- Algolia DocSearch: `ALGOLIA_APP_ID`, `ALGOLIA_SEARCH_API_KEY`, `ALGOLIA_INDEX_NAME`
+
+## Architecture
+
+### Tech stack
+
+- **Framework:** Docusaurus 3.1.1 (preset-classic)
+- **Styling:** Tailwind CSS 3.4.1 with `@morui/theme`
+- **CSS:** Sass with autoprefixer
+- **Markdown:** MDX with remark-math and rehype-katex
+- **Search:** Algolia DocSearch
+- **Deployment:** static output + nginx configs in repo
+
+### Key directories
+
+- `docs/` — MDX content (`build-on-morph/`, `about-morph/`, `how-morph-works/`, `morph-rails/`, …)
+  - `docs/build-on-morph/sdk/{classes,enumerations,functions,interfaces,type-aliases,variables}/` — **typedoc-generated API reference**; do **not** hand-edit these files or add frontmatter (including `doc_skill_id`), they will be overwritten on regeneration. See [`VISION.md`](./VISION.md) (Pairing Policy).
+- `skills/` — executable SKILL topics (mirrored on the site at `/skills/`)
+- `agents/` — agent role definitions (mirrored on the site at `/agents/`)
+- `src/components/` — React (`MorphRpc/`, `AltFee/`, `ApiExplorer/`, …)
+- `static/` — assets
+- `plugins/` — custom Docusaurus plugins
+- `scripts/` — doc processing utilities
+
+### Configuration
+
+- `docusaurus.config.js` — main config, sidebars reference (`sidebars.js`, `sidebars-skills.js`, `sidebars-agents.js`)
+- `sidebars.js` — nav (Get Started, Morph Chain, Node Operators, Learn, Morph Rails)
+- `tailwind.config.js` — theme tokens
+- `config.json` — Algolia DocSearch
+
+### Styling
+
+- Tailwind + `@morui/theme`; Sass in `src/css/`; overrides in `src/css/custom.scss`
+
+### Plugins
+
+- Markdown source plugin: `plugins/markdown-source-plugin.js` — post-build exports cleaned `.md` into `build/docs/`, `build/skills/`, and `build/agents/` (mirrors site routes)
+- Client redirects, Sass plugin, Mermaid theme
+
+## Documentation structure (sidebar)
+
+1. **Get Started** — quickstart, protocol overview  
+2. **Morph Chain** — SDKs, APIs, building on Morph  
+3. **Node Operators** — full node, validators  
+4. **Learn** — concepts and architecture  
+5. **Morph Rails** — infrastructure (e.g. AltFee, Reference Key)
+6. **Agent Skills** — `skills/` SKILL playbooks (site path `/skills/`)
+7. **Agents** — `agents/*.md` role definitions (site path `/agents/`)
+
+## Component patterns
+
+- Tailwind + Morui tokens; `morui-` prefix where applicable  
+- Demos (e.g. `MorphRpcClientDemo`) use JSON-RPC against Morph endpoints  
+
+## Deployment
+
+- Build output: `build/`  
+- Scripts: `build:mainnet`, `build:qanet` where applicable  
+
+## Key dependencies
+
+- `@morphnetwork/viem`, `@morui/theme`, `viem`, `lottie-react`
+
+## Development notes
+
+- MDX for embedded React; math via remark-math / rehype-katex  
+- Light/dark theming via custom tokens  
+- Single locale (en) for now  
+
+## Testing and changes
+
+- Automated checks live under `__tests__/`. When adding or changing **executable** helpers or behaviors covered by tests, extend or add tests there and run the project’s test script from `package.json`.
+
+## Secrets
+
+- Do not commit API keys, tokens, or `.env` contents. Follow `.gitignore`.

CLAUDE.md

@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Canonical handbook
+
+Day-to-day architecture, commands, and conventions live in [`AGENTS.md`](./AGENTS.md) — read it first. The doc–skill contract (why this repo exists as an "external brain" for Morph-facing agents) is in [`VISION.md`](./VISION.md). **Contributor norms** (pull requests, three-layer model, Skills-as-connectors checklist) live in [`CONTRIBUTING.md`](./CONTRIBUTING.md). This file only captures what Claude Code specifically needs on top of those.
+
+Optional personal overrides: `CLAUDE.local.md` (git-ignored). Nested `CLAUDE.md` files in subfolders may apply when working only in those paths.
+
+## What this repo is
+
+A Docusaurus 3.1.1 site (`morph-doc`) that doubles as the source of truth for **Morph Agent Skills** and agent definitions. Linked surfaces:
+
+- `docs/**/*.mdx|.md` — human-readable documentation. Long-form content, tables, demos.
+- `skills/<skill-id>/SKILL.md` — routable, executable summaries for AI agents. Each declares YAML frontmatter (`name`, `description`, `last_verified`, `verified_against`).
+- `agents/*.md` — agent role definitions (also routed at `/agents/` on the built site).
+
+Pairing is enforced: MDX pages marked `doc_skill_id: <id>` must match a `skills/<id>/SKILL.md` whose `name` equals `<id>`. See `__tests__/doc-skill-pairing.test.mjs`.
+
+## Commands
+
+```bash
+npm start              # docusaurus dev server
+npm run build          # production build (output: build/)
+npm run serve          # serve built site on port 8080
+npm run clear          # clear docusaurus cache
+npm test               # runs scripts/run-tests.mjs (all __tests__/*.test.mjs in a fixed order)
+npm run skill-ln       # symlink skills/<id>/ into .cursor/.claude/.openclaw/.windsurf/skills
+npm run agent-ln       # symlink agents/<name>.md into .cursor/.claude/.openclaw/.windsurf/agents
+```
+
+### Running a single test
+
+`npm test` executes the manifest in `scripts/run-tests.mjs`. To run one file directly:
+
+```bash
+node __tests__/<file>.test.mjs
+```
+
+New test files must be added to `TEST_FILES` in `scripts/run-tests.mjs` — `run-tests-manifest.test.mjs` enforces this.
+
+## Testing model
+
+Tests are plain Node ESM scripts (no framework). They exit non-zero on failure. Key guards to be aware of when editing docs or skills:
+
+- `doc-skill-pairing.test.mjs` — every MDX `doc_skill_id` must resolve to a skill whose `name` matches.
+- `morph-doc-skill-inventory.test.mjs` — frontmatter consistency across all `skills/*/SKILL.md`; warns (non-fatal) when `last_verified` is older than 90 days.
+- `morph-contracts-skill-tokenlist.test.mjs` — enforces parity between the `morph-contracts` Skill tables and `morph-bridge/public/morph-list/src/mainnet/tokenList.json`.
+- `skills-sidebar.test.mjs` — `sidebars-skills.js` must list every skill directory.
+- `vision-md.test.mjs` — VISION.md structural contract.
+- `examples-viem-alt-fee.test.mjs` — executable Alt Fee behavior tied to SDK docs.
+
+When you change an `actionable` or `fact-table` MDX page or the corresponding SKILL.md, re-stamp `last_verified` and update `verified_against` in the same change.
+
+## Skill authoring loop (the most common task)
+
+When the user asks for a new skill or a revision, follow [`agents/morph-doc-agent.md`](./agents/morph-doc-agent.md): **one goal → one skill directory**, `name` == folder name. The golden path:
+
+1. Land or update long-form content in `docs/` with `doc_skill_id` frontmatter when routing is needed.
+2. Create/update `skills/<id>/SKILL.md` — frontmatter + execution steps + self-check. Do **not** copy MDX body; link to the section.
+3. If adding a new skill id, register it in `sidebars-skills.js`.
+4. Run `npm test`. Fix the specific guard that fails — don't broaden scope.
+5. For fact-table skills, update `verified_against` to list every canonical path you cross-checked.
+
+See `VISION.md` for the pairing policy (which doc types require a skill) and the freshness contract.
+
+## Repo-specific conventions
+
+- **Never copy content between `docs/` and `skills/`.** Skills point into docs; docs never embed skill playbooks.
+- **Morph-specific fields** (e.g. Alt Fee `feeTokenID` / `feeLimit`, predeploy addresses) must match current docs — do not infer from Ethereum mainnet assumptions.
+- **Generated typedoc output** under `docs/build-on-morph/sdk/{classes,enumerations,functions,interfaces,type-aliases,variables}/` is regenerated; do not hand-edit frontmatter there.
+- **Agent workspace files** at repo root (`IDENTITY.md`, `SOUL.md`, `USER.md`, `TOOLS.md`, `HEARTBEAT.md`, `memory/`) are for the OpenClaw agent runtime — leave them alone unless the task is specifically about agent configuration. `USER.md` is git-ignored.

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to morph-doc
+
+This repository is the Morph documentation site (Docusaurus) and the **source of truth for Morph Agent Skills**. Before opening a pull request that touches `docs/`, `skills/`, or `agents/`, read the links below so changes stay consistent with the doc–skill contract.
+
+## Read first
+
+| Doc | Purpose |
+|-----|---------|
+| [`CLAUDE.md`](./CLAUDE.md) | Claude Code workspace entry: commands, skill authoring loop, links to AGENTS.md / VISION.md / CONTRIBUTING.md |
+| [`AGENTS.md`](./AGENTS.md) | Commands, directories, tests, day-to-day agent workspace operations |
+| [`VISION.md`](./VISION.md) | Documentation-as-SKILL vision, pairing policy, freshness metadata |
+| [`skills/README.md`](./skills/README.md) | `skills/` conventions, symlinks (`npm run skill-ln`), optional trigger-eval workflow |
+| [`agents/morph-doc-agent.md`](./agents/morph-doc-agent.md) | How to author or revise one Skill from a single goal |
+
+## Working with Claude Code
+
+Claude Code reads root [`CLAUDE.md`](./CLAUDE.md) when this repository is the active project. Use it together with this document: `CLAUDE.md` carries commands and the skill loop; **Morph knowledge base: Skills as connectors** (above) is the team contract for `docs/` / `skills/` / tests.
+
+- **Workspace root**: Open the **morph-doc** clone as the project root so paths (`docs/`, `skills/`, `__tests__/`) and `npm test` match CI and the guards described in `CLAUDE.md`.
+- **Global skills (optional)**: Run `npm run skill-ln` so `skills/<id>/` are symlinked into your global Claude skills directory (paths vary by install; see [`skills/README.md`](./skills/README.md)). Then other projects’ Claude Code sessions can load Morph skills without opening this repo.
+- **Global agents (optional)**: `npm run agent-ln` symlinks `agents/*.md` for tools that read global agent definitions.
+- **Single-topic Skill work**: Follow [`agents/morph-doc-agent.md`](./agents/morph-doc-agent.md); `CLAUDE.md` already routes the common “new or revise a Skill” loop there.
+- **Personal overrides**: Add a git-ignored `CLAUDE.local.md` at the repo root for machine-specific notes (see “Optional personal overrides” in [`CLAUDE.md`](./CLAUDE.md)).
+- **Verify before merge**: Run `npm test` after doc or skill edits (same expectation as `CLAUDE.md`).
+
+## Morph knowledge base: Skills as connectors
+
+Team norms for treating this repository as Morph’s **versioned knowledge base** and **external brain** for agents. This aligns with the **Three-layer model** in [`AGENTS.md`](./AGENTS.md) and the contract in [`VISION.md`](./VISION.md).
+
+### Three layers
+
+1. **Knowledge base**: Canonical facts, long-form narrative, tables, and demos live in `docs/**/*.mdx` for humans and site search. Do not paste full MDX pages into a Skill.
+2. **Brain**: **Execution Steps**, boundary notes, and **Self-Check** live in `skills/<skill-id>/SKILL.md`. Executable checks that must stay aligned with docs live in `__tests__/`; merge only after `npm test` passes.
+3. **Connector (Skill)**: Connects a short user or tool prompt to the right material—routing via YAML `name` / `description`, pairing MDX pages via `doc_skill_id`, and handing off via **Related Skills** without copying sibling Skill bodies.
+
+### Collaboration checklist
+
+- For **actionable** or **fact-table** topics, follow the pairing policy in `VISION.md`: keep `skills/<id>/SKILL.md` in sync, with `doc_skill_id` matching the Skill `name` and directory name (enforced by `__tests__/doc-skill-pairing.test.mjs` and related guards).
+- Skill bodies follow the **connector contract**: execution steps + pointers to specific `docs/` sections + optional Related Skills; large tables may live under `references/` with guidance in the Skill on when to open them.
+- When changing on-chain facts, contract addresses, RPC endpoints, or package versions, update `last_verified` / `verified_against` on affected Skills in the same PR (see `VISION.md`).
+- Register new skill directories in `sidebars-skills.js`. To load skills globally in an IDE across clones, use `npm run skill-ln` (see `skills/README.md`).
+- To tighten or relax how often a Skill is selected, see **Tuning description trigger rates** in `skills/README.md` and maintain an eval JSON modeled on `scripts/skill-trigger-evals.*.example.json`.
+
+### Mnemonic
+
+Write facts in `docs/`; write how to be found and executed in `skills/`; keep pairing verifiable with `doc_skill_id` and `npm test`.
+
+## Local setup
+
+- Install dependencies with your package manager (this repo commonly uses `pnpm` or `npm`).
+- `npm start` — Docusaurus dev server  
+- `npm test` — run all guards under `__tests__/` (required before merging doc–skill changes)
+
+## Pull requests
+
+- Run `npm test` and fix failures; do not broaden test scope to silence unrelated guards.
+- Do not hand-edit typedoc output under `docs/build-on-morph/sdk/{classes,enumerations,functions,interfaces,type-aliases,variables}/` or add `doc_skill_id` there (regenerated output).
+- Do not commit secrets (see `.gitignore` and `AGENTS.md`).
+
+For broader product context, see the repository [`README.md`](./README.md).