move skills

.github/scripts/doc-agent/README.md

@@ -5,19 +5,23 @@ Claude Agent SDK.
 
 ## What it does
 
-Two modes:
+Three modes:
 
 - **document** — Add Doxygen `/** */` documentation to a C++ file or
-  directory. The agent reads the file, related tests, and module skill
-  context, then writes documentation comments per the project standards in
-  `docs/DOCUMENTATION_STANDARDS.md`.
+  directory. For each target file, the agent reads the sibling
+  `<file>.ai.md` (high-signal prose generated by the athenah-ai pipeline),
+  the module skill, and the file itself, then writes Doxygen comments per
+  the standards in `docs/DOCUMENTATION_STANDARDS.md`.
 - **review** — Given a git diff range, detect documentation drift. Used by
   the `doc-review` GitHub Action and locally for testing.
+- **regen-skills** — Rebuild a module's skill file at
+  `docs/skills/soul/<module>.md` from the `.ai.md` files in that module
+  and the existing skill content.
 
 ## Requirements
 
-- Node.js >= 20
-- `ANTHROPIC_API_KEY` environment variable
+- Node.js >= 20.12 (for native `--env-file` support)
+- `ANTHROPIC_API_KEY` (in `.env` or exported in shell)
 - Tools the agent uses: `git`, `gh` (for `--pr`)
 
 ## Install
@@ -25,8 +29,13 @@ Two modes:
 ```sh
 cd .github/scripts/doc-agent
 npm install
+cp .env.example .env
+# edit .env and set ANTHROPIC_API_KEY
 ```
 
+The npm scripts auto-load `.env` via Node's `--env-file-if-exists` flag.
+You can also export the variables in your shell — both work.
+
 ## Build and lint
 
 ```sh
@@ -41,9 +50,7 @@ npm run check:fix     # lint + format + fix
 ## Usage
 
 ```sh
-export ANTHROPIC_API_KEY=sk-ant-...
-
-# Document a single file
+# Document a single file (reads sibling .ai.md if present)
 npm run document include/xrpl/basics/base_uint.h
 
 # Document an entire module
@@ -54,10 +61,22 @@ npm run review develop..HEAD
 
 # Review a PR
 npm run review -- --pr 1234
+
+# Regenerate a skill file from this module's .ai.md inputs
+npm run regen-skills protocol
+npm run regen-skills ledger
 ```
 
-When invoked outside the xrpld repo, set `XRPLD_ROOT` to the path of the
-checkout you want to operate on.
+When invoked outside the xrpld repo, set `XRPLD_ROOT` in `.env` to the path
+of the checkout you want to operate on.
+
+## ai.md context files
+
+The doc-agent reads a sibling `<file>.ai.md` next to each source file when
+documenting it. These are produced by the upstream `athenah-ai` pipeline
+and treated as the authoritative source of intent. They are gitignored
+(`*.ai.md` in `.gitignore`) and should be removed once the initial
+documentation pass is complete.
 
 ## Outputs
 
@@ -76,13 +95,15 @@ doc-agent/
 ├── biome.json
 ├── prompts/
 │   ├── document-file.md     # System prompt for documentation mode
-│   └── review-diff.md       # System prompt for review mode
+│   ├── review-diff.md       # System prompt for review mode
+│   └── regen-skill.md       # System prompt for regen-skills mode
 └── src/
     ├── index.ts             # CLI entry point
     ├── config.ts            # Paths, model, module-skill map
     ├── prompt-loader.ts     # Loads prompts + module skill context
     ├── document.ts          # Document mode
     ├── review.ts            # Review mode
+    ├── regen-skills.ts      # Regen-skills mode
     └── types.ts             # Shared types
 ```