@aperant/framework 0.6.2

package/docs/workflows.md

@@ -0,0 +1,194 @@
+# Declarative YAML Workflows (C17)
+
+Aperant's router encodes skill chains imperatively in TypeScript. That works,
+but it means every new composition requires editing `route.mjs` and the skill
+markdown. C17 adds a **complementary**, declarative mode: a YAML DAG where
+each node names a skill or agent invocation and edges encode dependencies.
+
+The declarative runner (`apt-tools wfrun`) can either:
+
+1. Execute the graph **inline** when every node is a `kind: tool` invocation
+   (deterministic `apt-tools …` subprocess calls), or
+2. Emit a **JSON run-plan** describing the waves a calling LLM/skill must
+   execute sequentially — the "invoke-point" mode for `kind: agent` and
+   `kind: skill` nodes.
+
+This page is the schema + invocation reference.
+
+## Overview
+
+YAML workflows complement the router — they don't replace it. The router
+handles autonomy, routing decisions, and session state. YAML workflows are
+for reusable, shareable chain-of-steps recipes that don't need the router's
+decision surface. Think: "plan → execute → verify" as a pattern you'd like
+to run on demand, or a diamond DAG of diagnostic tool invocations.
+
+## Schema Reference
+
+```yaml
+apiVersion: aperant.dev/v1     # reserved for forward compat; only this value accepted today
+kind: Workflow
+
+metadata:
+  id: <slug>                   # [a-z0-9][a-z0-9-]* — used as workflow_id in run artifacts
+  description: |               # optional free-text
+    …
+
+inputs:                        # optional; every name referenced as ${inputs.<name>} must appear here
+  - name: <identifier>         # [a-z0-9][a-z0-9_-]* — underscores allowed
+    required: true             # default true
+    default: <string>          # optional literal default
+    description: <string>      # optional
+
+nodes:                         # at least one
+  - id: <slug>                 # unique within nodes[]
+    kind: skill | agent | tool
+    depends_on: [<node-id>, …] # optional; every entry must match another node.id
+    outputs: [<identifier>, …] # optional; keys this node promises to produce
+
+    # Body fields are kind-discriminated:
+
+    # kind: skill
+    skill: <skill-name>
+    prompt: <string>           # optional, supports ${…} interpolation
+
+    # kind: agent
+    agent: <agent-name>
+    prompt: <string>           # optional, supports ${…} interpolation
+
+    # kind: tool
+    run:
+      command: <apt-tools subcommand>   # must be in the tool-command allowlist
+      args: [<string>, …]               # every entry supports ${…} interpolation
+```
+
+### Interpolation grammar
+
+Two reference forms are supported — nothing else:
+
+- `${inputs.<name>}` — resolves to the value supplied via `--input <name>=<value>`
+  (or the input's declared `default`).
+- `${<node-id>.outputs.<key>}` — resolves to an output captured from a
+  previous node. In **plan mode** (and inside `wfrun plan`), these references
+  are left literal because agent nodes haven't run yet; the caller is
+  responsible for substituting them before spawning downstream nodes.
+
+`\${…}` is left literal (the backslash is stripped). A bare `$` not followed
+by `{` is untouched.
+
+## Example Walkthrough — `diamond.yaml`
+
+```yaml
+apiVersion: aperant.dev/v1
+kind: Workflow
+metadata:
+  id: diamond
+
+nodes:
+  - id: a
+    kind: tool
+    run:
+      command: state
+      args: ["."]
+
+  - id: b
+    kind: tool
+    depends_on: [a]
+    run: { command: state, args: ["."] }
+
+  - id: c
+    kind: tool
+    depends_on: [a]
+    run: { command: state, args: ["."] }
+
+  - id: d
+    kind: tool
+    depends_on: [b, c]
+    run: { command: state, args: ["."] }
+```
+
+Line-by-line:
+
+- **`apiVersion` / `kind`** — structural discriminators. Missing either is a
+  hard error.
+- **`metadata.id: diamond`** — identifies this workflow; used in the
+  `workflow_id` field of all run artifacts and the first component of the
+  `run_id` (`wf-YYYYMMDD-HHmmss-<4-hex>`).
+- **`nodes[0]`** — the root. No `depends_on`, so it's placed in wave 1.
+- **`nodes[1]` + `nodes[2]`** — both depend on `a` only, so they end up in
+  wave 2 side-by-side. Nodes within a wave are executed **in parallel**
+  during `wfrun run` (each spawned as a separate `node apt-tools state .`
+  subprocess).
+- **`nodes[3]`** — the join. Waits for both b and c.
+
+Running `apt-tools wfrun plan packages/framework/workflows/examples/diamond.yaml`
+produces `waves: [[a], [b, c], [d]]` — exactly the shape above.
+
+## Invocation Recipes
+
+```bash
+# Parse + schema + DAG check, no execution:
+apt-tools wfrun validate packages/framework/workflows/examples/diamond.yaml
+
+# Resolve inputs + interpolate bodies + emit run-plan JSON:
+apt-tools wfrun plan packages/framework/workflows/examples/plan-execute-verify.yaml \
+  --input task_description="add a settings toggle"
+
+# Execute an inline workflow (all kind:tool) end-to-end; writes
+# .aperant/wfrun/{run-id}/{manifest,plan,result}.json:
+apt-tools wfrun run packages/framework/workflows/examples/diamond.yaml \
+  --project-dir .
+```
+
+All output is JSON. Non-zero exit status + a `{ "status": "error", … }`
+envelope signals a validation or runtime failure.
+
+## Run Artifacts
+
+A `wfrun run` writes three files under `.aperant/wfrun/{run-id}/`:
+
+| File             | Contents                                                                                      |
+| ---------------- | --------------------------------------------------------------------------------------------- |
+| `manifest.json`  | Run metadata: workflow_id, inputs, started_at, node/wave counts.                              |
+| `plan.json`      | The same envelope returned by `wfrun plan`: waves, inline_executable, reason, inputs.          |
+| `result.json`    | Only present for inline runs. Per-node `{node_id, command, args, exit_code, stdout_tail, stderr_tail, started_at, completed_at}`. |
+
+All writes go through `atomicWriteJson` (R3) and sit under the R11 outputs
+allowlist entry `.aperant/wfrun/**`.
+
+## v1 Limits
+
+| Feature                             | v1 Status          |
+| ----------------------------------- | ------------------ |
+| Loops / `forEach` over inputs       | NO                 |
+| `when:` conditionals                | NO                 |
+| Expression language (`${x+y}` etc.) | NO — literal paths only |
+| Output capture from `agent` nodes   | NO (follow-up task — caller reports outputs via a forthcoming `wfrun advance` command) |
+| Inline execution of `agent`/`skill` | NO — emitted as invoke points only |
+| Cross-machine / distributed runs    | NO                 |
+| Workflow versioning migrations      | NO (stay on `aperant.dev/v1`) |
+
+Hitting one of these is usually a sign you want the imperative router, not
+the declarative runner — or that the gap should graduate to a follow-up
+spec.
+
+## Naming Collision — `wfrun` vs `workflow`
+
+The existing `apt-tools workflow` subcommand is the C29 **phase-enforcement**
+runner: it tracks whether a lifecycle phase (plan / execute / verify / …)
+has been advanced correctly and gates downstream work on the right ordering.
+It has nothing to do with YAML composition.
+
+The declarative YAML runner therefore lives under a **new** top-level verb,
+`apt-tools wfrun`, rather than overloading `workflow`. This keeps both
+concepts individually discoverable (`wfrun = workflow-run`) and avoids
+breaking any script calling `workflow create / advance / status / destroy`
+today. The phase-enforcement command's tests remain green untouched.
+
+## Related
+
+- Spec-gaps entry: [C17](../../../docs/frameworks/spec-gaps.md#c17)
+- Phase-enforcement command (distinct): [`apt-tools workflow`](./workflow.md)
+  (if / when that page exists; source lives at
+  `packages/framework/src/cli/commands/workflow.mjs`).
+- DAG cycle-detection helper reused from: `src/cli/graph/depends-on.mjs`.

package/docs/worktree-ecosystems.md

@@ -0,0 +1,345 @@
+# Multi-language worktree ecosystems — cheatsheet
+
+This document explains the per-ecosystem quirks, anti-patterns, and flag
+matrices that drove the C54 worktree-bootstrap implementation. Read it when
+you're wiring a new ecosystem into the installer, debugging a hung install,
+or deciding whether to write a `task_isolation.bootstrap_cmd` override.
+
+**Enabled when?** `task_isolation.bootstrap_worktree: true` in
+`.aperant/config.json`. Off by default — existing projects get zero
+behavior change until they opt in via `/apt:setup` or by editing the
+config directly.
+
+**Per-task opt-out:** pass `--no-bootstrap` on `apt-tools worktree create`
+or match a `task_isolation.skip_bootstrap_for: ["<glob>"]` entry.
+
+**Custom command:** `task_isolation.bootstrap_cmd: ["./custom-install.sh"]`
+replaces the auto-detected invocation entirely — still runs under the
+same env-isolation + detached-child envelope.
+
+---
+
+## Per-ecosystem notes
+
+### pnpm
+
+**Canonical install:** `pnpm install --frozen-lockfile`
+
+**Why `--frozen-lockfile`?** Pins resolution to the exact versions in
+`pnpm-lock.yaml`. Without it, pnpm may update the lockfile silently if the
+`package.json` has drifted. `--frozen-lockfile` exits non-zero on drift,
+which is exactly the signal we want in a deterministic install path.
+
+**CAS safety across worktrees.** pnpm keeps a content-addressable store
+under `~/.local/share/pnpm/store/v3/` (or platform equivalent) that is
+shared across projects. Worktrees on the same host share the CAS safely
+because it's hashed by content. **Do not symlink `node_modules/` between
+worktrees** — pnpm's internal `node_modules/.pnpm/` directory contains
+per-project virtualized dependency graphs. Symlinking short-circuits the
+CAS and leaves the receiving worktree with a corrupted install.
+
+**`--prefer-frozen-lockfile`?** A softer variant that prefers but doesn't
+require an exact match. We don't use it: the bootstrap's contract is "the
+worktree is reproducible from the lockfile or the install fails loud."
+
+---
+
+### npm
+
+**Canonical install:** `npm ci`
+
+**`npm ci` vs `npm install`.** `npm ci` deletes `node_modules/` and
+reinstalls from `package-lock.json`. `npm install` resolves from
+`package.json` and updates the lockfile if needed. For a bootstrap we
+want deterministic — `npm ci` is mandatory. It also runs ~2x faster on
+cold caches because it skips the resolution pass.
+
+**Requires `package-lock.json`.** On a fresh repo with only
+`package.json`, `npm ci` refuses to run. That's surfaced as
+`install_status: "failed"` with the npm error text in the log.
+
+---
+
+### yarn classic
+
+**Canonical install:** `yarn install --frozen-lockfile`
+
+Yarn classic (1.x) is a legacy ecosystem that many repos still run. The
+`--frozen-lockfile` flag is the equivalent of `npm ci` — refuses to
+update `yarn.lock`.
+
+---
+
+### yarn-berry
+
+**Canonical install:** `yarn install --immutable`
+
+**PnP mode + no `node_modules/`.** Yarn Berry's default mode is Plug'n'Play:
+no `node_modules/` tree, dependencies resolved via `.pnp.cjs` at runtime.
+Detected via `.yarnrc.yml` with `nodeLinker: pnp` (or `pnpm`). Under PnP
+the post-install tree is dramatically smaller (no copy per project) but
+some tools (editors, eslint resolvers) need PnP-aware plugins.
+
+**`.yarn/cache/` sharing.** Berry caches packed tarballs under
+`.yarn/cache/` inside each project. Worktrees on the same host can safely
+share the cache via symlink IF they're on the same Berry version — but we
+do NOT do this automatically because a version-mismatch silently corrupts
+the cache. If you need the share, do it by hand, make sure every
+worktree runs the same Berry version, and re-check after a `corepack`
+upgrade.
+
+---
+
+### bun
+
+**Canonical install:** `bun install --frozen-lockfile`
+
+**Lockfile format migration.** Pre-Jan 2025, bun shipped `bun.lockb` — a
+binary format bun could read/write natively but git diff tools couldn't
+show line-by-line changes. Post-Jan 2025, bun defaults to `bun.lock` — a
+text format that diffs cleanly. The detector handles both; if only
+`bun.lockb` is present it surfaces a non-fatal warning in the ecosystem
+entry recommending migration.
+
+**Migrate by running:** `bun install --save-text-lockfile` (or in modern
+bun, a bare `bun install` on a repo with `bun.lockb` produces `bun.lock`
+automatically). Commit both files until your team is on a bun version
+that reads `bun.lock`, then delete `bun.lockb`.
+
+---
+
+### uv vs poetry
+
+**Canonical uv install:** `uv sync --frozen`
+**Canonical poetry install:** `poetry install --no-root --sync`
+
+**pyproject.toml coexistence hazards.** A single `pyproject.toml` can
+declare BOTH `[tool.uv]` and `[tool.poetry]` blocks and each tool will
+happily act on its own without warning the other. This is a foot-gun: the
+two tools disagree on how to resolve `dependencies` in the PEP-621
+`[project]` block vs the Poetry-style `[tool.poetry.dependencies]`. The
+detector picks `uv` when a `uv.lock` is present, else `poetry` when
+`poetry.lock` is present, else whichever `[tool.*]` block exists. If
+neither lockfile exists and both tool blocks are present, pick one in
+the PROJECT.md or the install will be non-deterministic.
+
+**uv caches aggressively.** `~/.cache/uv/` shares wheels across projects,
+similar to pnpm's CAS. Worktrees share safely.
+
+---
+
+### pip-venv
+
+**Canonical install:** `python -m venv .venv && .venv/bin/pip install -r requirements.txt`
+
+**Two-step wrapper.** Implemented as `shell_wrapper` in ecosystem-commands.mjs
+because there's no single-invocation pip command that creates a venv AND
+installs into it.
+
+**Never copy `venv/` between worktrees.** `.venv/bin/python` and
+`.venv/bin/pip` are shebang-linked to absolute paths:
+`#!/home/you/project-A/.venv/bin/python`. Copy the directory into
+project-B and every executable stops working — or worse, silently runs
+project-A's interpreter against project-B's code. Create a fresh venv
+per worktree. Hard-link the wheel cache if you want the speed.
+
+---
+
+### cargo
+
+**Canonical install:** `cargo fetch --locked`
+
+**NEVER `cargo build`.** `build.rs` is arbitrary Rust code that runs at
+build time — it can do anything a Rust program can do, including reading
+env vars, opening network connections, and writing to the filesystem.
+Moving `build` to install time would broaden the RCE attack surface
+without commensurate gain. We defer `build` to the verify stage where it
+runs under the same env envelope but with a cleaner expectation.
+
+**`target/` size impact.** Rust's incremental build directory explodes
+over time: per-worktree `target/` directories can cost 10+ GB each. The
+CI answer is sccache; the local-dev answer is `cargo sweep --time 30` or
+occasionally blasting `target/` between worktree switches. **Never share
+`target/` between worktrees on different branches.** Rust's incremental
+compilation cache invariant assumes all edges of a single source graph —
+a `target/` built from branch A reused on branch B can silently produce
+miscompiled code with no warning.
+
+---
+
+### go
+
+**Canonical install:** `go mod download`
+
+**`go.sum` is a checksum file**, not the resolution source of truth.
+`go.mod` declares dependencies; `go.sum` locks content hashes. `go mod
+download` uses both to prefetch the module graph; it does not require
+`go.sum` to exist (it will create one on first run).
+
+**Module proxy.** `GOPROXY=proxy.golang.org,direct` by default. The env
+allowlist drops this to just the proxy — you can't shell out to arbitrary
+git hosts during install.
+
+---
+
+### bundler (Ruby)
+
+**Canonical install:** `bundle install --jobs 4 --retry 3`
+
+**Gemfile.lock.** Lockfile presence is optional; bundler happily resolves
+from `Gemfile` alone. We don't pass `--frozen` by default because many
+Ruby monorepos rely on the install updating the lockfile — gate via
+config if your project requires frozen behavior.
+
+---
+
+### composer (PHP)
+
+**Canonical install:** `composer install --no-interaction --prefer-dist`
+
+**`--no-interaction`** is mandatory; `--prefer-dist` pulls pre-built
+archives instead of cloning via git, which avoids needing git access
+inside the install env.
+
+---
+
+### gradle
+
+**Canonical install:** `./gradlew --no-daemon dependencies`
+
+**`--no-daemon` is MANDATORY.** Gradle's daemon keeps a JVM hot across
+invocations. Without `--no-daemon`, parallel worktrees hitting the same
+daemon deadlock on the lock file in `~/.gradle/daemon/`. The crash mode
+is silent: the second install hangs, eventually timing out with a cryptic
+"Daemon is stopped" error.
+
+**Users can keep their daemon for interactive work.** The `--no-daemon`
+flag only affects our invocation; user shells don't inherit it. We do
+NOT kill orphaned daemons the user left running — that's beyond scope.
+
+**GRADLE_OPTS env.** The spawn helper sets `GRADLE_OPTS=
+-Dorg.gradle.daemon=false` belt-and-suspenders so even a `build.gradle`
+that tries to re-enable the daemon via `gradle.properties` can't.
+
+---
+
+### CocoaPods (iOS)
+
+**NOT AUTOMATED.** The cheatsheet covers this ecosystem because it's a
+common question, but the installer does NOT orchestrate `pod install`.
+Reasons:
+
+1. **`.xcworkspace` mutation hazard.** `pod install` mutates the
+   `.xcworkspace/` Xcode project descriptor in place. Multiple parallel
+   pod runs racing on the same workspace corrupt the project.
+2. **Platform-specific toolchain.** CocoaPods needs Ruby + the cocoapods
+   gem + `pod setup` having run once. We don't want to drag those deps
+   into the install envelope.
+
+If you need iOS bootstrap, set `task_isolation.bootstrap_cmd:
+["./ios-bootstrap.sh"]` and own the sequencing in your own script.
+
+---
+
+## Cross-cutting matrices
+
+### Frozen-install flag matrix
+
+| Ecosystem | Frozen-install flag | Behavior on drift |
+|---|---|---|
+| pnpm | `--frozen-lockfile` | exits non-zero |
+| npm | `ci` (implicit) | exits non-zero |
+| yarn classic | `--frozen-lockfile` | exits non-zero |
+| yarn-berry | `--immutable` | exits non-zero |
+| bun | `--frozen-lockfile` | exits non-zero |
+| uv | `--frozen` | exits non-zero |
+| poetry | `--sync` | updates to match lockfile (no "fail on drift") |
+| pip-venv | n/a | pip has no frozen flag; pin via `requirements.txt` |
+| cargo | `--locked` | exits non-zero on Cargo.lock mismatch |
+| go | n/a | go.sum acts as checksum only |
+| bundler | `--frozen` (not default) | exits non-zero when passed |
+| composer | `--no-install` + `--install` split | lockfile consulted when present |
+| gradle | `--no-daemon` (not frozen-related) | uses dependency constraints |
+
+### Offline-prefer flag matrix
+
+| Ecosystem | Offline flag | Required for | 
+|---|---|---|
+| pnpm | `--offline` | fully offline install (cache-only) |
+| npm | `--prefer-offline` | best-effort offline |
+| yarn | `--offline` | fully offline install |
+| bun | `--offline` | fully offline install |
+| uv | `--offline` | fully offline install |
+| cargo | `--offline` | fully offline (cache-only) |
+| go | `GOFLAGS=-mod=mod` + `GOPROXY=off` | offline, module cache only |
+
+We don't pass offline flags by default — the bootstrap is expected to
+have network. Set these via `bootstrap_cmd` if you're in an air-gapped
+env.
+
+### Lifecycle-script exec matrix (which ecosystems run arbitrary code)
+
+| Ecosystem | Runs arbitrary code during install? | Mitigated by |
+|---|---|---|
+| pnpm | YES (postinstall, preinstall, scripts) | env allowlist + HOME stub |
+| npm | YES | env allowlist + HOME stub |
+| yarn | YES | env allowlist + HOME stub |
+| bun | YES | env allowlist + HOME stub |
+| uv | NO (wheels are static) | n/a |
+| poetry | rarely (setup.py build hooks) | env allowlist |
+| cargo | n/a (`fetch` doesn't build) | we skip `cargo build` |
+| go | NO (`mod download` is metadata+archive) | n/a |
+| bundler | YES (extconf.rb native builds) | env allowlist |
+| composer | rarely (scripts block in composer.json) | --no-scripts is NOT default; allow scripts so `composer install` works on real repos |
+| gradle | YES (build.gradle is Groovy/Kotlin) | --no-daemon + env allowlist |
+
+The env allowlist + stubbed HOME means even "runs arbitrary code"
+ecosystems can't exfiltrate credentials or talk to non-allowlisted
+registries.
+
+---
+
+## Anti-patterns
+
+### Never symlink `node_modules/` between worktrees
+
+pnpm's CAS bypass → corrupted install. The `.pnpm/` hoisting tree
+under `node_modules/.pnpm/` contains per-worktree virtualized dependency
+graphs. Sharing it across worktrees leaves both in a half-reset state
+after the next `pnpm install`.
+
+If you really need to save space across 12 parallel worktrees, rely on
+pnpm's content-addressable store (already shared globally under
+`~/.local/share/pnpm/store/`) — that's the intended sharing surface.
+
+### Never copy venv between worktrees
+
+Python venvs hardcode absolute paths in their bin shebangs:
+`#!/home/you/project-A/.venv/bin/python`. Copy the directory to
+project-B and `.venv/bin/pip` points at project-A's interpreter — or
+worse, at a path that no longer exists. The symptoms are subtle
+("why does my import fail? I'm in the right venv"). Create a fresh venv
+per worktree; hard-link the wheel cache if speed matters.
+
+### Never share target between worktrees on different branches
+
+Rust's incremental compilation cache invariant assumes every edge of a
+single source graph. When you point two worktrees on different branches
+at the same `target/`, the incremental cache's assumption is violated
+and the compiler can silently produce miscompiled code — no warning, no
+build error, just incorrect runtime behavior.
+
+If you want to share build output, use `sccache` (distributed
+compilation cache that's branch-aware) or use the cargo workspace
+feature where all crates share a single `target/` within one repo —
+that's supported, and the invariant holds.
+
+---
+
+## Framework references
+
+- Implementation: `packages/framework/src/cli/install/ecosystem-commands.mjs`
+- Security scanner: `packages/framework/src/cli/install/manifest-scanner.mjs`
+- Spawn envelope: `packages/framework/src/cli/install/detached-spawn.mjs`
+- Config: `.aperant/config.json → task_isolation.*`
+- Skill guidance: `packages/framework/skills/apt-execute/SKILL.md` (step 2a)

package/examples/plugin-template/README.md

@@ -0,0 +1,79 @@
+# Aperant Framework -- Plugin Template
+
+A starting point for building a custom framework adapter for the [Aperant](https://aperant.dev) platform. Copy this directory, fill in your framework's artifact declarations and mapper logic, and Aperant will render your framework's output in its standard UI.
+
+## Files
+
+| File | Purpose |
+| ---- | ------- |
+| `manifest.json` | Declares your framework's identity, lifecycle stages, artifacts, and mapper paths. Conforms to the `FrameworkManifest` interface. |
+| `mappers/context-mapper.ts` | Example mapper that translates your context-stage artifacts into `AperantContextView`. |
+| `mappers/plan-mapper.ts` | Example mapper that translates your plan-stage artifacts into `AperantPlanView`. |
+
+## Getting Started
+
+1. **Copy this directory** into your own project:
+   ```bash
+   cp -r examples/plugin-template ~/my-framework-plugin
+   cd ~/my-framework-plugin
+   ```
+
+2. **Install the framework package** as a dev dependency:
+   ```bash
+   npm install --save-dev @aperant/framework
+   ```
+
+3. **Edit `manifest.json`** with your framework's details:
+   - Set `id` to a unique identifier for your framework (e.g., `"bmad"`, `"speckit"`)
+   - Set `name` to a human-readable name
+   - Update each stage's `artifacts` array with the filenames your framework produces
+   - Point each stage's `mapper` field to the compiled JS path of your mapper
+
+4. **Implement the mapper functions** for each stage. The two included mappers (`context-mapper.ts` and `plan-mapper.ts`) demonstrate the pattern:
+   - Receive a `Map<filename, fileContent>` of native artifacts
+   - Parse your native format
+   - Return the normalized Aperant UI shape
+
+   You will also need `progress-mapper.ts` (returns `AperantProgressView`) and `verify-mapper.ts` (returns `AperantVerificationView`).
+
+5. **Replace inline types with imports** from `@aperant/framework/types`:
+   ```typescript
+   import type {
+     AperantContextView,
+     AperantPlanView,
+     AperantProgressView,
+     AperantVerificationView,
+   } from "@aperant/framework/types";
+   ```
+
+6. **Build with TypeScript** and confirm your mappers compile cleanly:
+   ```bash
+   npx tsc
+   ```
+
+7. **Install for local testing** by copying the built output to the plugins directory:
+   ```bash
+   mkdir -p ~/.aperant/plugins/my-framework
+   cp -r dist/ manifest.json ~/.aperant/plugins/my-framework/
+   ```
+
+## How It Works
+
+1. When Aperant loads a framework plugin, it reads `manifest.json` to discover stages and mapper paths.
+2. For each stage, Aperant collects the native artifact files declared in the manifest.
+3. It passes them as a `Map<filename, fileContent>` to the corresponding mapper function.
+4. The mapper parses the native format and returns the normalized UI shape.
+5. Aperant renders the shape in its standard components (decisions table, Kanban board, progress bar, verification dashboard).
+
+## Type Reference
+
+For the complete API reference including all UI shape interfaces, provider capabilities, and mapper contracts, see [docs/api.md](../../docs/api.md).
+
+## Key Interfaces
+
+- **`FrameworkManifest`** -- Top-level plugin declaration (id, name, version, stages)
+- **`StageManifest`** -- Per-stage artifact declarations and mapper path
+- **`AperantContextView`** -- Normalized context (decisions, scope, deferred items)
+- **`AperantPlanView`** -- Normalized plan (tasks, waves, dependencies)
+- **`AperantProgressView`** -- Normalized progress (percent, activity feed)
+- **`AperantVerificationView`** -- Normalized verification (score, dimensions, gaps)

package/examples/plugin-template/manifest.json

@@ -0,0 +1,30 @@
+{
+	"id": "my-framework",
+	"name": "My Custom Framework",
+	"version": "0.1.0",
+	"stages": [
+		{
+			"stage": "context",
+			"artifacts": [{ "nativeName": "requirements.md", "role": "context", "format": "markdown" }],
+			"mapper": "./mappers/context-mapper.js"
+		},
+		{
+			"stage": "plan",
+			"artifacts": [
+				{ "nativeName": "task-breakdown.json", "role": "plan", "format": "json" },
+				{ "nativeName": "design-notes.md", "role": "summary", "format": "markdown" }
+			],
+			"mapper": "./mappers/plan-mapper.js"
+		},
+		{
+			"stage": "execute",
+			"artifacts": [{ "nativeName": "progress.json", "role": "progress", "format": "json" }],
+			"mapper": "./mappers/progress-mapper.js"
+		},
+		{
+			"stage": "verify",
+			"artifacts": [{ "nativeName": "qa-report.json", "role": "verification", "format": "json" }],
+			"mapper": "./mappers/verify-mapper.js"
+		}
+	]
+}