# Docs

Documentation for Meerkat TaskPanel, grouped by **reader**: what a session must follow while
working in this repository, what the product is designed to do, and what an operator runs.

## Documentation layers and reference direction

This repository has five documentation layers, and references cross them in one direction
only:

- **Design record — the Meerkat-specific design pages under `docs/`.** What this system is and
  why. They are never installed.
- **Repository maintenance — `docs/maintenance/` and `CONTRIBUTING.md`.** How to develop, verify
  and change this repository. It is never installed and a target project does not receive it.
- **Project documentation — the target project's own `docs/` and root files.** `docs/tech-spec.md`,
  `docs/architecture.md`, `docs/adr/`, `docs/agents/`, `docs/ops/`, `README.md`,
  `CONTRIBUTING.md`, `CHANGELOG.md`, `CLAUDE.md`, `AGENTS.md` and `GLOSSARY.md` are supplied by
  the project and may be read at runtime. A project may also supply
  `docs/agents/decision-policy.md` to refine the director's default E1–E5 mapping. They are the
  authority for that project's facts, not for this repository's design. Installed skills may
  discover `docs/agents/` and `docs/ops/`, but they must not name this repository's
  maintainer-only files in them.
- **Deployed artifacts — `skills/**`, `src/**` and the installer scripts.** Copied to agent homes
  and run. A skill is self-contained after install: it may point at another installed skill or
  at the target project's own documents, never back into this repository's design docs.
- **Per-project initialization — the project's `CLAUDE.md` / `AGENTS.md`.** Written by the
  host's `init` skill; `setup-meerkat` supplies the requirements (it points at the installed
  skills and the project's own `docs/agents/`, never at this tree).

A design page may name a deployed artifact in a clearly labelled "deployed contract" pointer;
it must not present that artifact as the authority for a design rule. Comments in `src/**` and
the installer scripts may cite a design page as provenance, but nothing read at runtime may read
this tree. The reverse is never allowed: an installed skill that cites `docs/scheduling.md`,
`docs/lifecycle.md` or another repository-only page dangles after installation
(`test/skill/installability.test.mjs`), even in a comment. The whole of `docs/maintenance/` is
repository-only, as are `docs/ops/install.md`, `docs/ops/observability.md` and
`docs/ops/publishing.md`; a target project may supply a file at the same path, but this
repository's copy is not its documentation. `docs/agents/` is the home of a project's own board
rules (`issue-tracker.md`, the historical `issue-tracer.md`, `triage-labels.md`, `domain.md`,
`create-card.md`, and the optional `decision-policy.md`); those are project
documentation and
remain addressable. The same path can be a design record here and project
documentation in another repository (`docs/architecture.md`, `docs/agents/*`); the guard asks
whether a target project is guaranteed to have the file, not which layer the path belongs to.

## Agent execution

The rules and gates a session follows while working in this repository. The tracker files are
the per-repository outputs of the Matt Pocock integration; the standard and system record are
this repository's own.

| Document | Contents |
|---|---|
| [tech-spec.md](tech-spec.md) | This repository's standard: the numbered rules a change must satisfy (stack, structure and enumerations, naming, errors and contract, configuration, logging, tests and gates, release, project documents), each naming its enforcement, plus the security toolchain and its decision policy. |
| [architecture.md](architecture.md) | The system record: purpose and boundary, the layered style, module boundaries and the one-way dependency, the data model, the contract, configuration, logging, security boundaries, the canonical directory tree and the vertical slice. Reconstructed from the tree and accepted by the human on 2026-10-30. |
| [adr/](adr/) | Architecture decision records: one file per durable decision, numbered, with the status vocabulary. |
| [issue-tracker.md](agents/issue-tracker.md) | How this repository's work is tracked as cards: the `taskctl` workflow, the commands the engineering skills expect, and the conventions that differ from a hosted tracker. |
| [domain.md](agents/domain.md) | How the engineering skills consume this repository's domain documentation (`GLOSSARY.md`, ADRs, `design/`). |
| [triage-labels.md](agents/triage-labels.md) | The five canonical triage roles and the label strings this repository uses for them. |
| [create-card.md](agents/create-card.md) | This project's own card-creation choices — scope, acceptance-mode selection and the epic boundary; a thin override of the `meerkat` skill's manual, never board data. |

## Repository maintenance

How to develop, verify and change this repository. These pages are repository-only: they are
never installed and a target project does not receive them.

| Document | Contents |
|---|---|
| [development.md](maintenance/development.md) | The operational facts you cannot read off the code: the two build layers (`dist` vs `web/dist`, the offline `web/` build) and the server invariants (one writer per data directory, the bounded stop, lock contention as a 503). Commands and layout live in `CLAUDE.md`. |
| [docker.md](maintenance/docker.md) | Why verification and the four-agent-kind installs run in a container; the image build, the offline `web/` build stage, profiles and troubleshooting. |
| [contract.md](maintenance/contract.md) | The contract snapshots — the HTTP API (routes, error codes, wire fields) and the CLI surface (`taskctl` commands, flags, envelope keys): what each freezes, the `--update` workflow, and the pre-push / pre-tag / CI gates. |
| [migration.md](maintenance/migration.md) | The append-only SQL schema gate, and the note recording the MCP integration's removal. |

## Design

How the product behaves, and why.

| Document | Contents |
|---|---|
| [lifecycle.md](lifecycle.md) | The card lifecycle: flow A (create, claim, wait, deliver, accept), the delivery round and the delivery gate, flow B (the review card's identity, dispatch, verdict and outcomes), the workflow pass, containers, the enforcement layers, the standing states, and the decisions and limits behind them. |
| [acceptance.md](acceptance.md) | The acceptance model — who may close a card: the single-layer card vocabulary (`off | auto | human`), resolution at creation and why the fallback is `auto`, the three modes, review's independence from the closer, the standing states, the three enforcement layers, and the known limits. |
| [scheduling.md](scheduling.md) | The scheduling model: the ping/continue clocks, the deterministic loop passes, the fire-only cost gate, the atomic-claim dispatch, the event subscriber, the three-agent-kind trigger differences, and why OpenClaw installs the board skill only. |
| [sla.md](sla.md) | The SLA design: the wait-time model, why the board computes and the loop notifies, the threshold table and tier ladder, the working-hours basis, the alert tuple, the row detectors, de-duplication and pre-emit re-check, the peer watchdog, and the decisions with their costs. |
| [events.md](events.md) | The event system's design: the append-only activity log and its revision cursor, the SSE contract and its delivery semantics, each consumer's refresh policy (board, ledger, feed, loop, card watcher), the local event hub, the event catalogue, and the decisions and costs behind them. |
| [projects.md](projects.md) | The project subsystem: the id and the effective identifier prefix (derivation, uniqueness, immutability), what a project carries, its lifecycle and wire surface, the server-ranked `PROJECTS` order, and why the working directory lives in the machine-local `projects.json` instead. |
| [roles.md](roles.md) | The role layer: discovery from installed role skills, the install-time kind order, the claim set versus the writer identity, the local `roles.json` catalog (`role list`/`role sync`), the CLI assignee check, and how it differs from the board's `actors` dictionary. |
| [access.md](access.md) | Access and security design: the local-first trust model, the request gate (loopback / allow-list / token), the credential's shape, storage and rotation, managing access from the panel and the CLI, what remote clients get today (and why the built board is loopback-only), the API surface's other guards, and the limits this design does not cover. |
| [im-integration.md](im-integration.md) | The planned IM integration: the plugin host + `channel-kit` contract, how “needs a human” is pushed, how replies are anchored and written as human comments, the resident IM session, and the per-platform adapter strategy (third-party SDKs, independent packages). |

## Operations

Installing, releasing and watching a deployment.

| Document | Contents |
|---|---|
| [install.md](ops/install.md) | Installing: `npx` / npm and source-checkout methods, the server runtime tree at `~/.meerkat-taskpanel`, and installing the skill into Claude Code, OpenClaw, Codex or Pi; `install.sh` usage, the per-agent-kind table and flags. |
| [publishing.md](ops/publishing.md) | Releasing a version: npm packaging / publish (the tarball is a runnable board carrying `web/dist`), the git tag + GitHub Release pipeline, and the per-agent publication steps (Claude Code marketplace / OpenClaw / Codex / Pi). |
| [observability.md](ops/observability.md) | The metrics sidecar (`/metrics`, the SLO `/health` verdict, Prometheus rules, OTLP export) and the processes' own structured logs: levels, the text line, request correlation, redaction, `taskd.log` ownership and rotation, and the `TASKD_LOG_*` keys. |

The agent-facing skill definitions live beside the skills themselves:
[`../skills/meerkat/SKILL.md`](../skills/meerkat/SKILL.md) and
[`../skills/meerkat/references/cli.md`](../skills/meerkat/references/cli.md).

Start with the [README](../README.md) for what the project is and its current status. `design/`
is a live oracle for tests and a record of past rounds, not documentation: its citations of
`docs/…` paths name the pre-move layout and are deliberately not kept in step with this tree.

## On `ARCHITECTURE.md` citations

`ARCHITECTURE.md` is **not part of this repository** — there is no such file in the tree, and
none in the git history. Older code and prose nonetheless cite it by section (`ARCHITECTURE
§1`, `§3`, `§4.1`–`§4.8`, `§5.1`/`§5.4`, `§7`/`§7.1`, `§8`, `§9.1`, `§13`), across `src/**`,
`scripts/**`, `test/**`, `docs/**` and `design/**`.

Read those citations as **historical orientation only** — none of them resolves to a file in
this repository. Where a topic has a live authority, the citation names it explicitly:

| Cited as | Live authority |
|---|---|
| The system design, layers and tree | [architecture.md](architecture.md) (reconstructed from the tree, accepted 2026-10-30) |
| Project ordering (`ARCHITECTURE §4.6`) | [`../design/DESIGN.md`](../design/DESIGN.md) §20, implemented by `src/foundation/project-order.mjs` |
| Container verification (`ARCHITECTURE §9.1`) | [docker.md](maintenance/docker.md) |

**Do not add a new `ARCHITECTURE.md` citation.** Name the live document instead — the system
record is [architecture.md](architecture.md).

## On `docs/verify/`

This tree used to hold **verification-run records**: one directory per `T-<card>` work lane,
each carrying that lane's report plus the harness, evidence dumps and screenshots that
produced it. They were never documentation. They accounted for **224 of the 237 files and
98.8% of the bytes under `docs/`**, nothing in the repository read them, and because `docs` is
in `package.json`'s `files` while `docker/Dockerfile` does `COPY . .`, they were being shipped
in the npm package and baked into the container image — carrying a developer's home directory
with them, which is exactly the disclosure `scripts/verify/paths.mjs` exists to prevent.

They now live **outside the repository**, in each card's own workspace under `repo-verify/` —
the same place the `design/fidelity-rNN.md` round records already send the oracle and probe
harnesses they keep out of the repository. So a bare `T-<card>` citation you meet in `src/**`,
`test/**`, `web/**` or `design/**` (for example `T-20261014-150729`) names a **card**, not a
file in this repository.

**Do not land run records here again.** `test/fixtures/host-paths-allowlist.json` is now
deliberately empty, so `scripts/verify/paths.mjs` fails on *any* tracked file carrying a
host-absolute path — and all 65 records it used to exempt carried one.

## On retired audits

`docs/` holds **live** documentation: what a reader needs to install, run, operate or extend
the repository. A one-off audit is not that. `ui-align-retirement-audit.md` lived here until
2026-10-17 and was removed alongside the run records above — a reconciliation pinned to two
historical commits (`b7d6379`, `f61e02a^`), by then 97 commits behind `dev`, of a tool
(`ui-align`) that no longer exists anywhere in this tree, and referenced by nothing.

Its question was real — whether retiring `ui-align` cost checking power — but its **answer does
not survive checking.** Most rows it lists as having "no guard whatsoever" name guards that are
present in `test/web/blocks.contract.mjs` *at the very commit it pins*: it calls
`[data-access-panel]` `count: 1` unguarded, while `b7d6379` asserts exactly that bound. **So its
headline number is not a backlog — do not open work against it.** Two of the hooks it names
(`[data-side-text]`, `[data-caret]`) really are unnamed by every harness, but that is two
absence-claims, not fifty-two lost guards.