docs: split README into for-humans + for-agents with mermaid diagrams#68
Merged
LanNguyenSi merged 2 commits intomasterfrom May 6, 2026
Merged
docs: split README into for-humans + for-agents with mermaid diagrams#68LanNguyenSi merged 2 commits intomasterfrom
LanNguyenSi merged 2 commits intomasterfrom
Conversation
The previous README mixed two audiences: the human operator who installs harness and writes the manifest, and the agent who reads the audit triumvirate and emits ledger entries. Split into docs/for-humans.md (operator guide: install, mental model, first hour, diagnostics cheat sheet) and docs/for-agents.md (workflow lifecycle, policy/ledger sequence, CLI cheat sheet by side-effect class, audit triumvirate). README shrunk to a landing page that picks audience. Three mermaid diagrams added: a system flowchart LR in for-humans, a workflow stateDiagram-v2 and a policy/ledger sequenceDiagram in for-agents. CLI verbs cross-checked against src/cli/index.ts. No em dashes in new prose. Docs-only, no source changes; 711/711 tests still green. Refs agent-tasks 1358f4eb. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The intercept verb is registered as a subcommand under `policy` (src/cli/index.ts:872), not at top level. Reviewer caught the mislabel in the sequenceDiagram participant and the prose under it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 6, 2026
Merged
LanNguyenSi
added a commit
that referenced
this pull request
May 6, 2026
Bump package.json 0.6.0 -> 0.7.0. Roll up CHANGELOG [Unreleased] into [0.7.0] - 2026-05-06 with a one-paragraph headline plus operator note. PR refs (#65, #66, #67, #68, #69) added to each entry. README now references v0.7.0 in the prose and gains a status checklist row for the workflows-as-data + session-export + docs-split set. Two version-pinned tests bumped to match the new binary header. Theme: workflows-as-data and full-session audit forensics. No schema bump (still version: 1); all new manifest fields are additive and parse identically against 0.6.0 manifests. Refs agent-tasks 1fe55885. Co-authored-by: Lan Nguyen Si <nguyen-si@publicplan.de> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/for-humans.md(operator path: install, mental model, first hour, diagnostics cheat sheet) anddocs/for-agents.md(workflow lifecycle, policy/ledger sequence, CLI cheat sheet by side-effect class, audit triumvirate, things-not-to-do).flowchart LRsystem map in for-humans, astateDiagram-v2workflow lifecycle and asequenceDiagrampolicy/ledger contract in for-agents.src/cli/index.ts. Reviewer caught one mislabel (harness interceptis actuallyharness policy intercept, a subcommand underpolicy); fixed in the second commit.Why
The previous README mixed two readers: the operator who installs harness and writes the manifest, and the agent who reads the audit triumvirate and emits ledger entries. Splitting them makes each path actionable in one read.
Refs agent-tasks
1358f4eb.Scope cut
Test plan
src/cli/index.ts(16 verbs verified).grep -n "—"returns zero in README + both new files).intercept→policy intercept) addressed in the second commit.