skillshop 0.0.0-stage → 2.1.0

package/README.md

@@ -1,3 +1,281 @@
-# Temporary Holding Version
+# Skillshop
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Skillshop installs and manages agent skills. Its CLI includes a bundled skill registry, with the same named install, update, and agent configuration commands as the earlier `skillz` CLI. It also lets project owners export skills from their own npm packages. A skill is a directory containing `SKILL.md` and any supporting files.
+
+The command is `skillshop`; `sk` runs the same CLI. The previous `skillz` command is no longer an executable alias. Existing `.skillz-lock` and `~/.skillz` state remain readable.
+
+## For users: manage skills
+
+### Install and configure Skillshop
+
+```bash
+npm install --global skillshop
+skillshop init
+```
+
+`init` asks which agents you use and saves their destinations in `~/.skillshop/config.json`. Change the selection later with `skillshop config agents`. Codex and OpenCode use `.agents/skills` inside projects and `~/.agents/skills` for user-level installs. Copilot and Claude use their own skill directories. Shared destinations get one copy.
+
+### Install a named skill
+
+List the skills bundled with Skillshop, then install one:
+
+```bash
+skillshop list
+skillshop one-shot
+# Equivalent: skillshop install one-shot
+```
+
+Run a project install inside a Git repository. Skillshop copies the skill into each configured project destination and records managed copies in `.skillshop-lock`. It also installs the `skillshop` guidance skill. The lockfile and managed skill directories go into the repository's local Git exclude file, leaving unrelated skill directories alone.
+
+To install a named skill for your user account instead:
+
+```bash
+skillshop one-shot --global
+# Equivalent: sk install one-shot --global
+```
+
+For Codex or OpenCode, this writes `~/.agents/skills/one-shot`. A global install replaces an existing skill directory with that name, including local edits and extra files. Global installs use `~/.skillshop/global-skills.json` for bookkeeping. Each CLI run reconciles recorded installations; it does not install the entire bundled registry.
+
+### Update or remove skills
+
+```bash
+skillshop update
+skillshop update one-shot
+skillshop update --push
+skillshop uninstall one-shot
+skillshop uninstall one-shot --global
+```
+
+`update` replaces skills managed in the current project's lockfile. `update --push` updates registered projects. Neither command updates global copies; reinstall a global skill by name with `--global`. Project uninstall removes only a skill recorded in `.skillshop-lock`. Global uninstall removes the named skill from configured user directories.
+
+An exact version such as `skillshop one-shot@2026.8.21` checks the currently bundled version. It does not fetch a historical release. Use `skillshop migrate` to discover older lockfiles and register their repositories.
+
+### Manage agent instructions
+
+```bash
+skillshop agents
+skillshop agents --global
+```
+
+The local command updates a managed block in the nearest existing `AGENTS.md`. The global command updates the supported user instruction files. Sibling `*.block.md` fragments are composed in filename order. Text outside Skillshop's managed blocks is preserved.
+
+### Use skills from another package
+
+A distributor can declare which exported skills a global npm install should place in your user skill directory:
+
+```bash
+npm install --global @example/skill-library
+```
+
+Those declared skills are copied during the package's install script. This package installer targets `~/.agents/skills` by default, independently of the agents selected with `skillshop init`. Updating the package replaces the same named user skills. If scripts are disabled, run `skillshop install-user /path/to/installed-package` manually.
+
+To copy one exported skill into a project instead:
+
+```bash
+npm install @example/skill-library skillshop
+npx skillshop import @example/skill-library:review
+```
+
+The `library:skill` argument names an installed package and one skill it exports. The command copies the skill to `.agents/skills/review` in the current project. Use `--to` for another destination or `--global` to copy it to `~/.agents/skills/review`. This is a snapshot. Reimport with `--force` to replace an existing project copy. `skillshop resolve @example/skill-library:review` reports its source location without copying it.
+
+### Example: one user, two scopes
+
+Suppose you use Codex and work in `~/work/sample-app`, which is already a Git repository. Select Codex when `skillshop init` prompts, then install one bundled skill for every project and another only for this app:
+
+```bash
+skillshop init
+skillshop one-shot --global
+cd ~/work/sample-app
+skillshop changelog
+```
+
+The global command writes `~/.agents/skills/one-shot/SKILL.md`. The project command writes `.agents/skills/changelog/SKILL.md` and `.agents/skills/skillshop/SKILL.md` inside `sample-app`, then records both managed skills in `.skillshop-lock`. It does not copy `one-shot` into the project. Running `skillshop update` in `sample-app` refreshes the locked project skills; run `skillshop one-shot --global` again to replace the global copy.
+
+Package imports are separate from this lockfile workflow. `import` copies a snapshot from another package; `skillshop update` does not refresh that snapshot. `export` names a skill for consumers of a package and does not install it anywhere.
+
+## For project owners: distribute skills
+
+### 1. Export the skills
+
+In an npm package, put each skill in a directory with a `SKILL.md`. For example:
+
+```text
+my-library/
+  package.json
+  .agents/skills/review/SKILL.md
+  .agents/skills/triage/SKILL.md
+```
+
+For example, `.agents/skills/review/SKILL.md` could contain:
+
+```markdown
+---
+name: review
+description: Review a proposed code change
+---
+
+# Review
+
+Read the diff, identify concrete defects, and cite the affected files.
+```
+
+Keep any references or scripts needed by the skill beside its `SKILL.md`; Skillshop copies the whole directory.
+
+Add Skillshop, initialize the export list, and name the skill you want to publish:
+
+```bash
+npm install skillshop
+npx skillshop library init
+npx skillshop export skill:review ./.agents/skills/review
+npx skillshop export skill:triage ./.agents/skills/triage
+```
+
+This writes `skillshop.library.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "exports": {
+    "skill:review": "./.agents/skills/review",
+    "skill:triage": "./.agents/skills/triage"
+  }
+}
+```
+
+The `exports` map is an explicit allowlist. Skillshop does not scan your repository for other skills. `skillshop export` also builds the library; run `skillshop build` after editing the JSON by hand. The build generates `skillshop.manifest.mjs`, adds the package's `./skillshop` export, and includes declared local skill directories in `package.json#files` when that field exists. Commit the resulting package files with your source.
+
+### 2. Declare user-level installation, if needed
+
+To copy selected skills during a global npm install, add `skillshop.userInstall` and the generic lifecycle command to the distributor's `package.json`:
+
+```json
+{
+  "name": "@example/skill-library",
+  "version": "1.0.0",
+  "dependencies": {
+    "skillshop": "^2.1.0"
+  },
+  "files": [],
+  "scripts": {
+    "prepack": "skillshop build",
+    "postinstall": "skillshop install-user . --if-global"
+  },
+  "skillshop": {
+    "userInstall": ["skill:review"]
+  }
+}
+```
+
+Every `userInstall` entry must be unique and appear in `skillshop.library.json`. In this example, `skill:review` installs for the user on a global npm install. `skill:triage` remains available for explicit project imports. The runtime dependency makes the `skillshop` command available to npm's `postinstall` script. `--if-global` skips the user copy on a project-local install. npm's `--ignore-scripts` skips `postinstall` entirely.
+
+An install replaces each declared destination directory. If a later release removes a name from `userInstall`, Skillshop does not delete a copy previously installed in a user's directory.
+
+### 3. Check and pack the package
+
+```bash
+npx skillshop library list
+npx skillshop validate
+npx skillshop build
+npm pack --dry-run
+```
+
+Check that the npm package contains `skillshop.manifest.mjs`, every exported `SKILL.md`, and any assets those skills need. The export list controls what Skillshop can resolve; it does not prevent your own broad `files` patterns from publishing other files. A real `npm pack` and global install from its tarball are useful checks before a release.
+
+After checking the tarball, publish the package with `npm publish`. Use `npm publish --access public` for a public scoped package.
+
+### Example: what happens after publication
+
+With the two-skill package above published as `@example/skill-library`, a global install copies only the declared `skill:review` to the user's skill directory:
+
+```bash
+npm install --global @example/skill-library
+# ~/.agents/skills/review/SKILL.md now comes from the package
+```
+
+An application that needs `skill:triage` can install the package locally and copy that exported skill into its own repository:
+
+```bash
+cd ~/work/sample-app
+npm install @example/skill-library skillshop
+npx skillshop import @example/skill-library:triage
+```
+
+After the distributor publishes an update, reinstalling the package globally replaces the user's `review` directory. The application's `triage` snapshot stays as it was until the application updates the package and imports again with `--force`. The two installation paths are independent.
+
+### Re-export a skill from another library
+
+A package can expose a selected upstream skill under its own name:
+
+```bash
+npm install @example/upstream
+npx skillshop export skill:review --from @example/upstream --skill skill:review
+```
+
+The resulting export in `skillshop.library.json` is:
+
+```json
+{
+  "skill:review": {
+    "from": "@example/upstream",
+    "skill": "skill:review"
+  }
+}
+```
+
+That object is one entry inside the manifest's `exports` map. The upstream package must be a runtime dependency or a non-optional peer dependency. Re-exporting is explicit; depending on another library does not expose all of its skills.
+
+## CLI and JavaScript API
+
+```text
+skillshop init
+skillshop config agents
+skillshop list
+skillshop <name> [--global]
+skillshop install <name> [--global]
+skillshop update [name]
+skillshop update --push
+skillshop uninstall <name> [--global]
+skillshop agents [--global]
+skillshop migrate [root ...]
+skillshop library init
+skillshop library list
+skillshop export skill:<name> <directory>
+skillshop export skill:<name> --from <package> [--skill skill:<source-name>]
+skillshop unexport skill:<name>
+skillshop validate
+skillshop build
+skillshop resolve <library>:<skill>
+skillshop import <library>:<skill> [--global] [--to <directory>] [--force]
+skillshop install-user [package-dir] [--if-global] [--to <skills-dir>]
+```
+
+`init` and `list` keep their bundled-registry meanings. `library init`, `library list`, `validate`, and `build` operate on the package library in the current directory. In a `library:skill` reference, `library` can be an installed package name or a local package directory. `import` defaults to `.agents/skills/<skill>`; `--global` replaces `~/.agents/skills/<skill>`. `unexport` changes the package's public skill list; it does not delete the source directory. Remove a skill from `userInstall` before unexporting it.
+
+Applications can use the same operations without invoking the CLI:
+
+```js
+import { exportSkill, reexportSkill, buildSkillLibrary } from 'skillshop/export';
+import { resolveSkill, importSkill } from 'skillshop/import';
+import { installDeclaredUserSkills } from 'skillshop/user-install';
+```
+
+For example, an application can read an exported skill directly from an installed package, or copy it into a workspace it manages:
+
+```js
+import { readFile } from 'node:fs/promises';
+import { resolveSkill, importSkill } from 'skillshop/import';
+
+const reference = '@example/skill-library:triage';
+const { manifestPath } = await resolveSkill({ reference });
+const instructions = await readFile(manifestPath, 'utf8');
+// Pass instructions to your agent runtime.
+
+await importSkill({
+  reference,
+  overwrite: true,
+});
+```
+
+`resolveSkill` leaves the skill inside the installed package. `importSkill` copies its complete directory, including files alongside `SKILL.md`. Set `overwrite: true` only when the application intends to replace an existing destination.
+
+`importSkill({ overwrite: true })` replaces a destination. Its optional `merge: true` mode overlays packaged files and preserves unrelated destination files. User-level installation always uses replacement, even when called through `installDeclaredUserSkills`.

package/agents-content/000_communication-writing.block.md

@@ -0,0 +1,11 @@
+## Communication and writing
+
+- Write directly and concisely. Prefer short, distinct sentences over long compound ones.
+- Do not overuse em dashes. There are periods, commas, semicolons, and exclamation marks. Use them.
+- Remove hedges and filler that add no information. Keep technical terms when they add precision.
+- Avoid exact counts unless the number matters. "All the callers" is usually better than "all 4 callers."
+- Short, natural reactions are fine. Use "Good catch!" rather than an inflated response.
+- Avoid throat clearing, restating the question, routine process narration, and closing offers. Brief accountability or correction is fine when it helps the reader.
+- Do not explain in prose what a table or diff already makes clear.
+- State genuine uncertainty briefly. Do not add defensive caveats or pre-empt objections nobody raised.
+- Brevity must not hide important behavior, risk, uncertainty, or evidence.

package/agents-content/001_external-actions.block.md

@@ -0,0 +1,9 @@
+### Approval for external actions
+
+All external actions require explicit approval before proceeding. Even on autopilot mode, do not post without explicit written authorizaton from the user.
+
+- Before posting or editing a PR comment, review reply, issue comment, Slack message, or other external message, show me the exact draft and get an explicit OK. This includes edits to existing messages.
+- Before resolving review threads, requesting reviewers, or changing other visible review state, describe the exact action and get an explicit OK.
+- Create an issue, epic, or PR only when I explicitly request it. Before opening one, show me its proposed title and body and get an explicit OK.
+- A direct request to update an existing PR or issue body authorizes that update without another approval. Fetch the latest body from the host immediately before editing it.
+- Pushing requested commits does not require another approval.

package/agents-content/AGENTS.md

@@ -0,0 +1,11 @@
+### Baseline tone
+
+This applies to every text that you write.
+
+Adopt a skeptical, questioning approach. Don't default to praise, criticize my ideas, provide counterpoints, dig deeper. I need you to find the blind spots in my thinking and account for them, in a straight shooting and constructive way.
+
+Don't overuse adjectives, don't compliment or criticize my arguments in a personalized way, just attend to the facts and topics. Tell it like it is; don't sugar-coat responses. Also don't explicitly mention you're NOT praising me or actively say you're “getting to the point”. Don't comment on your tone at all.
+
+When explaining things, provide depth of concepts, be extensive, with context, clarity and explanation of concepts along the way.
+
+{{ blocks }}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "skillshop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.1.0",
+  "description": "Build, export, resolve, and install portable agent skill libraries",
+  "type": "module",
+  "bin": {
+    "skillshop": "./src/cli.js",
+    "sk": "./src/cli.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./library": "./src/library.js",
+    "./export": "./src/export.js",
+    "./import": "./src/import.js",
+    "./user-install": "./src/user-install.js",
+    "./specifier": "./src/specifier.js"
+  },
+  "files": [
+    "agents-content/",
+    "skills-content/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills-content/architecture-scanner/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: architecture-scanner
+description: Architecture scanner and documentation generator. Use when scanning the codebase architecture, updating architecture docs, or generating architecture documentation.
+metadata:
+  author: Daniel Fosco
+  version: "2026.8.30"
+---
+
+# Architecture Scanner Skill
+
+> Triggered by: "scan the codebase architecture", "update the architecture", "update arch", "generate architecture docs", "scan arch", "full update", "full architecture update", "full refresh architecture"
+
+## What This Does
+
+Generates documentation files in `.agents/architecture/` that describe every architecturally significant file in the codebase. The system has two layers:
+
+- **`architecture.index.md`** — The architectural overview. Groups files by category (ordered and configured via the `categories` array in `files.json`) and includes prose summaries. Categories with `"priority": "critical"` get 2-3x more detailed overviews. A reader should be able to understand the system's architecture from this file alone.
+- **Per-file docs** (`{filepath}.md`) — Detailed documentation for individual files, including what they do, how they work (with code samples), their dependencies, and dependents. Every file reference is cross-linked to its architecture doc.
+
+## How to Execute
+
+The scanner handles repository mechanics. The agent handles architectural interpretation and writing. The primary modes are:
+
+```bash
+.agents/skills/architecture-scanner/scan.sh --full
+```
+
+- Runs: discovery -> placeholder creation -> index skeleton creation -> verify
+- Existing authored docs and an existing authored index are preserved.
+
+After `--full`, run `--enrich-all` for a first scan or `--enrich` for an incremental scan, then perform the writing pass described below. The command output is a worklist for the agent, not final documentation.
+
+```bash
+.agents/skills/architecture-scanner/scan.sh --enrich
+```
+
+- Runs: agent-enrichment planning only (no file writes)
+- The script prints a JSON worklist (`create`, `update`, `delete`) with per-file targets and manual next steps.
+- Use an agent action to write/refresh each listed `.agents/architecture/{path}.md` using goal-first narrative and architectural context.
+- The JSON worklist includes these fields per target: `path`, `doc`, `category`, `importance`, `exports`, `hint_dependencies`, `hint_dependents`, `enrichment_focus`, and optional `existing_goal_preview`.
+
+```bash
+.agents/skills/architecture-scanner/scan.sh --enrich-all
+```
+
+- Runs: agent-enrichment planning for every non-low file in `files.json`, even if unchanged.
+- `--enrich-all` is useful when the user requests a full rewrite, style reset, or comprehensive prose refresh.
+- For unchanged files, tasks are returned with `reason: full_rewrite`, not `source_changed`.
+- The output remains an agent-only plan (`create`, `update`, `delete`) with no file writes.
+
+```bash
+.agents/skills/architecture-scanner/scan.sh --steps "discover,docs,index,verify"
+```
+
+- Runs only selected steps in order. Supported step names:
+  - `discover` (scan and refresh `files.json`)
+  - manifest/docs (print full manifest / create missing placeholders)
+  - `stale` (print changed/removed manifest)
+  - `enrich` (agent-enrichment plan: changed files only)
+  - `enrich-all` (agent-enrichment plan: all non-low files)
+  - `index` (index from existing docs)
+  - `verify` (coverage/linkback consistency check)
+
+### Step 0: Inventory repository topology (required)
+
+Before discovery, inspect tracked manifests and workspace configuration for the repository's actual ecosystems. Examples include `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, and language-specific workspace files. Use `git ls-files` or the repository's workspace tooling so generated dependency directories and external worktrees are not mistaken for packages.
+
+Read every relevant root and workspace manifest to understand package names, responsibilities, entry points, and internal dependencies. Do not assume a `packages/*` layout or that one manifest represents the entire repository.
+
+### Step 1: Discover files
+
+```bash
+.agents/skills/architecture-scanner/scan.sh --discover
+```
+
+This scans the repo using discovery rules and creates or updates `files.json` in the skill folder. If `files.json` doesn't exist yet, it creates it with default priorities. If it already exists, it **adds new files** and **removes deleted files**, but **preserves user-set `importance` values** — those are never overwritten.
+
+Discovery includes common root and workspace manifests. Review and extend `DISCOVERY_RULES` when the repository uses another ecosystem or layout; a scanner cannot infer architectural importance from filenames alone.
+
+Run this first to ensure the file list is current.
+
+### Step 2: Determine what needs to be done
+
+Run `--stale` to get the incremental manifest when you want change-aware updates. For scripted full flows, use `--full` or `--steps` directly.
+
+```bash
+.agents/skills/architecture-scanner/scan.sh --stale
+```
+
+This uses **git history** to detect changes: it finds the most recent commit that touched `.agents/architecture/`, then diffs against `HEAD` to identify changed source files, and also includes uncommitted (staged/unstaged) changes.
+
+`--stale` returns a JSON object with three incremental buckets:
+
+- **`files`** — docs to create/update:
+  - `"missing"` = source exists but doc does not (added/new file docs)
+  - `"stale"` = source changed since last architecture update
+- **`removed`** — docs to delete because source was removed/moved or is no longer tracked
+- **`index`** — whether `architecture.index.md` should be regenerated (`"status": "stale"`) and why
+
+If `files` and `removed` are both empty and `index.status` is `"fresh"`, docs are up to date.
+
+**When `--stale` suggests a full scan:** If more than 50% of documented files need updates, output includes `"suggestion": "full_scan"` and a message. In this case, switch to a full scan:
+
+```bash
+.agents/skills/architecture-scanner/scan.sh --manifest
+```
+
+You can also force a full scan explicitly with:
+
+```bash
+.agents/skills/architecture-scanner/scan.sh --full
+```
+
+This outputs every non-low file regardless of change status. Use this for:
+- **First-time runs** (no architecture docs exist yet)
+- **Template changes** (when the doc format itself changed, so all docs need regeneration)
+- **When `--stale` suggests it** (many files changed across multiple commits)
+- **When the user explicitly requests a full scan**
+- **When the user says natural-language variants like "full update" / "full refresh"**
+
+**Low importance files are excluded from both manifests and should NOT get architecture docs.**
+
+### Step 3: Agent writes the documentation
+
+The scanner creates only missing placeholder files. For each entry in `files` (from `--stale`) or each entry in the full manifest (`--manifest`/`--full`), the agent must read the actual source and write the architecture document at:
+
+```
+.agents/architecture/{filepath}.md
+```
+
+For example:
+- `src/application/core/loader.js` → `.agents/architecture/src/application/core/loader.js.md`
+- `vite.config.js` → `.agents/architecture/vite.config.js.md`
+
+#### For NEW files (status `"missing"`, or first full scan):
+
+The placeholder already has the required headings. Read the source, then replace every agent comment with source-grounded prose. The manifest's `doc` field contains the exact relative path to use.
+
+#### For STALE files (status `"stale"`):
+
+The doc already exists but the source file has changed. Follow this process:
+
+1. **Read the source file** to understand what changed
+2. **Read the existing doc file** to see what's already documented
+3. **Use the edit tool** to update only the sections that are affected by the source changes — preserve accurate authored context
+4. Do NOT recreate the file from scratch — make surgical updates
+
+#### For REMOVED files (status `"removed"` in `removed` array):
+
+Delete the stale architecture doc file referenced by the entry's `doc` field. If any docs are deleted, regenerate the index in Step 4.
+
+**What to check when updating a stale doc:**
+- Has the file's purpose changed? → Update **Meaning**
+- Have exports/functions/components changed? → Update **Composition**
+- Have imports changed? → Update **Dependencies**
+- Have downstream consumers changed? → Update **Dependents** (re-grep)
+- Any new edge cases or behavior changes? → Update **Notes**
+
+#### Doc template
+
+Each doc file MUST follow this template:
+
+```markdown
+# `{filepath}`
+
+<!--
+source: {filepath}
+category: {category}
+importance: {importance}
+-->
+
+> [← Architecture Index](../architecture.index.md)
+
+(Adjust the relative path based on nesting depth — e.g., `../../architecture.index.md` for files 2 levels deep like `src/application/core/loader.js.md`)
+
+## Meaning
+
+{1-2 paragraph architectural summary: what this file means in the system, why it exists, what responsibility it owns, and what would break or become unclear without it. This must be readable by someone unfamiliar with the codebase.}
+
+## Composition
+
+{Detailed description of the file's structure: what it exports, key functions/components, internal organization, type signatures, parameter details. Include code samples from the actual source file to illustrate key exports, signatures, and patterns — don't just describe them in prose.}
+
+## Dependencies
+
+{List of significant imports — what this file depends on, and why}
+
+## Dependents
+
+{What depends on this file — who imports it, derived by grepping}
+
+## Notes
+
+{Any non-obvious behavior, edge cases, circular dependency considerations, or architectural decisions worth noting. Omit this section if there's nothing notable.}
+```
+
+**Rules for writing docs:**
+- Read each file's actual content before writing its doc — do NOT guess
+- The **Meaning** section is the most important — it should be a clear, standalone conceptual summary (1-2 paragraphs), not a restatement of the filename or category
+- The remaining sections (Composition, Dependencies, Dependents, Notes) are all top-level headings — do NOT wrap them in a `<details>` element
+- **Include code samples** — when describing exports, function signatures, component props, data shapes, or usage patterns, include actual code snippets from the source file. This makes docs scannable and concrete.
+- **Cross-link file references** — every time a file path is mentioned anywhere in the documentation (Goal, Composition, Dependencies, Dependents, Notes, or the index), it MUST be a markdown hyperlink to that file's architecture doc. Use relative paths from the current doc to the target doc. For example, in a doc at `.agents/architecture/src/application/context.jsx.md`, a reference to the loader would be written as [`src/application/core/loader.js`](./core/loader.js.md). If the referenced file has no architecture doc (e.g., low-importance files), link to the source file on GitHub or leave it as plain text with a backtick code span.
+- The "Dependents" section should be derived by grepping for imports of this file
+- For `medium` importance files, keep it concise — shorter Meaning, fewer code samples
+- For `high` importance files, write a thorough Meaning (2 paragraphs), comprehensive Composition with multiple code samples, and complete dependency/dependent lists
+
+### Step 4: Agent writes the index
+
+```bash
+.agents/skills/architecture-scanner/scan.sh --index
+```
+
+This creates `architecture.index.md` only when it is missing. If it already exists, the script preserves it. The agent must read and update the index after writing file docs.
+
+When the index is missing, `--index` creates its structural skeleton. When `--stale` reports `index.status: "stale"` because files changed, added, or were removed, the agent edits the existing index directly so its authored overview and concepts are preserved.
+
+The agent MUST write the repository overview and category concepts. Read the `categories` array in `files.json` to determine category order, display names, and priority levels. The final index should follow this structure:
+
+```markdown
+# Architecture Index
+
+> Architecture guide for this repository. The scanner maintains structure; the agent maintains meaning.
+
+## Repository overview
+
+{2-4 paragraphs explaining what the repository is for, the packages or modules and runtime surfaces it contains, the central user/system concepts, and the major flow between them. Base this on every relevant manifest and the source graph.}
+
+## {Category Name}
+
+{Conceptual overview: what this category represents, why it exists, what it owns, and how it relates to other categories.}
+
+- [`path/to/file.js`](./path/to/file.js.md) — {one-line description}
+- [`path/to/other.js`](./path/to/other.js.md) — {one-line description}
+
+## {Next Category}
+...
+```
+
+**Category configuration** is defined in `files.json` under the `categories` array:
+
+```json
+"categories": [
+  { "id": "application", "name": "Application Core", "priority": "critical", "order": 1 },
+  { "id": "config", "name": "Configuration", "priority": "normal", "order": 5 }
+]
+```
+
+- **`order`** — Controls the display order of categories in the index (ascending)
+- **`name`** — The display heading used in the index (`## {name}`)
+- **`priority`** — Controls the depth of the overview:
+  - **`critical`** — The overview for this category should be 2-3x longer than normal. Write 3-4 paragraphs covering key concepts, data flow, architectural decisions, and how the parts interact. Include code samples or diagrams in the overview itself when helpful. These are the categories a new contributor must deeply understand.
+  - **`normal`** — Standard 1-2 paragraph overview explaining purpose, key patterns, and relationships between files.
+
+**Rules for the index:**
+- Category sections are ordered by the `order` field in the `categories` array
+- Each category section gets an architectural overview — length determined by `priority`
+- Each link gets a brief one-line meaning statement, written from the file's Meaning section
+- **Cross-link file references** — every file path mentioned in the overview text must link to its architecture doc (same rule as per-file docs)
+- The opening architecture narrative must reflect the **full repository inventory** from Step 0, not just the packages or modules currently documented in one category
+- Write for someone unfamiliar with the codebase — the index is the entry point to understanding the architecture
+
+### Step 5: Verify
+
+- Confirm every file in the manifest has a corresponding `.md` doc
+- Confirm every entry in `removed` had its doc file deleted
+- Confirm `architecture.index.md` links to all docs
+- Confirm every doc has a backlink to the index
+
+### Step 6: Commit
+
+```bash
+git add .agents/architecture/ .agents/skills/architecture-scanner/
+git commit -m "Update architecture documentation"
+```

package/skills-content/architecture-scanner/files.json

@@ -0,0 +1,10 @@
+{
+  "categories": [
+    { "id": "config", "name": "Configuration", "priority": "normal", "order": 1 },
+    { "id": "entry", "name": "Entry Points", "priority": "critical", "order": 2 },
+    { "id": "interface", "name": "Interfaces", "priority": "normal", "order": 3 },
+    { "id": "core", "name": "Core Implementation", "priority": "critical", "order": 4 },
+    { "id": "test", "name": "Tests", "priority": "low", "order": 5 }
+  ],
+  "files": []
+}