Rewrite the wiki greenfield: current design only, no history
harnessed has no users yet, so the wiki carries no compatibility debt and should
describe the current design rather than how it got here. Historical framing was
actively misleading: a reader could not tell a decision that still binds from
one that was reversed.
harnessed-design.md — rewritten (731 lines -> 211). The old spec had drifted far
past patching: it described a lib/manifests/<harness>.yaml mechanism that was
never built, a gemini harness that no longer exists, a harnesses: field on
recipes that is now explicitly banned, a harness: field on stacks that was
removed, image-baked skills where the assembler now fans them into the profile,
and hatago as its own pod container where it now runs in-process. Status
markers ("proposed", "to verify") were never resolved. The new document is the
why: the problem, composition as the product, runtime composition, harness
independence, one MCP hub, Claude-canonical format, credentials by reference,
supply chain, pnpm, state, secrets, the capability oracle, and the host CLI.
codebase/ — corrected nine factual errors in the regeneration: HostBackend
placed in hostrun.py when both backends live in launcher.py; omp expanded as an
invented name rather than oh-my-pi; a claim that no lockfile is committed when
uv.lock is tracked; a claim that CI never runs podman when live.yml sets
HARNESSED_PODMAN=1 post-merge and nightly; overstated coverage gaps for
svcstate.py and aoe.py; a duplicated backend.py tree entry; a wrong recipe
count; and a mocking convention stated without its one exception. Re-added the
launcher.py size concern the regeneration dropped.
Removed as pure history: done/ (six closed planning docs), guides/beads.md (a
guide for a retired tracker), and recipe-build-findings.md (an authoring log).
Every reference to them was repaired rather than left dangling, including two
in troubleshooting.md and the index entries in Home.md and _Sidebar.md.
Also unpinned the design-doc section numbers cited from troubleshooting.md —
the rewrite renumbered the document, and a pinned number rots on the next edit.
Reviewed the whole diff before publishing, including the regenerated files I did
not author: no credentials, no personal paths, no private hostnames or internal
names. Credential mentions describe the reference-never-replicate mechanism,
which is already public.
df6077a
docs: the default stack and recipe, and first-run overlay seeding
`--extends` defaults to the stack name `default`, which the repo now actually
ships (with a `default` recipe carrying the harnessed-catalog authoring skill).
Document what that baseline is, why it holds no policy fields and no MCP
servers, and how to replace it from the user overlay.
Also documents first-run seeding of `~/.config/harnessed/catalog/recipes/default`
and its one cost: the seeded copy wins on name clash, so later releases cannot
improve it until the user deletes theirs.
5b0a356
docs: retire ROADMAP.md — roadmap tracking lives in beads
Every item in the file was reconciled against the beads database before
deletion. Most were already covered (shipped work, or beads that kept the
same suffix: ylz, 72j, 7rh, rlw, w8k, c98, ec5, asg, fut, l71, 5ki, 9cf).
Four items had no bead and were filed first, so nothing is lost:
harnessed-9j0 bundle antigravity + codex + opencode (was main-9sv)
harnessed-6du headroom backlog recipe (was main-tl6)
harnessed-5wm hindsight backlog recipe (was main-13i)
harnessed-2fg one-shot install script, deferred (was main-qbi)
Two items were confirmed moot rather than missing: main-liw (a lint for
`exit` in SOURCED init scripts — init scripts are executed now, per
harnessed-zi6) and main-3va (flat `rules:` .md fan-out, fixed and covered
by test_synclinks.py). The superseded-branch cleanup section was already
done — none of those branches exist.
Home.md and _Sidebar.md lost their ROADMAP links in the previous commit.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
dd5a547
docs: bring the guides up to the shipped model
The generated codebase maps were regenerated today; these are the
hand-written guides that had drifted behind them.
extending-stacks: drop the "Status: proposed" header — extends: shipped
(schema.py _locate_parent_stack / _resolve_stack_extends, 8 tests in
test_stack_extends.py). Three specced rules had no implementation and are
removed rather than left as false promises: the recipe-variety extend
ban, the repo-cannot-extend-overlay rule, and the credential-forwarding
provenance notice. The last two are security rules and are tracked as
harnessed-s7v. Also corrected: ssh_keys IS union-inherited
(_STACK_UNION_FIELDS) with enforcement at the mount point
(_trusted_ssh_keys drops non-overlay keys); state: is a full block
replace, not a per-key merge.
stacks: the harness is not a stack property. Removed `harness: claude`
from the schema block, both worked examples, and the `harnessed new`
output — the singular field is rejected by the validator, and
`harnessed new` has no --harness flag at all (it rejects a stack NAMED
after a harness instead). Added instructions: and extends:. Repointed
three dead examples at gsd-core_repowise.
recipe-authoring: document install:, env:, and setup.script — the
install mechanism was previously absent from the guide entirely.
container-filesystem: per-stack volumes replaced the image-layer model
(harnessed-8px.21); the profile is composed into the volume, not mounted
over it as seven per-subdir ro binds.
secrets + codebase maps: CLAUDE_CODE_OAUTH_TOKEN is the primary claude
auth path, and no credential file is mounted when one is configured. The
.credentials.json path is a legacy fallback that seeds a per-instance
rw COPY — so "credentials are never copied" was wrong in both the guide
and the generated maps.
harnessed-update: new guide. The command shipped with no documentation.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
e1729a2
docs: absolute wiki links, a current Home, and the service manifest as it now is
Three things, all of which made the published wiki disagree with reality.
Links: 160 relative targets across 27 pages resolved to raw.githubusercontent.com instead of the
wiki page, because the wiki flattens directories (guides/beads.md -> /wiki/beads). Rewritten
mechanically by `mise run docs`; all 62 distinct URLs verified 200.
Home: called docs/ a "git submodule" and told the reader to bump a pointer that does not exist --
it is an unpinned live clone, refreshed with `git -C docs pull`. Its guide list was also missing six
guides that have shipped since (extending-stacks, recipe-catalog, system-prompt, beads, pulumi,
git-hooks); the sidebar was missing container-filesystem.
service-authoring: documented 5 of the manifest's 12 fields and marked `port` required when the
schema requires only name and image -- a service on a unix socket has no port at all. Adds scope,
publish, socket, client_env, data, exclusive_lock and sync, including what `publish: stable` buys
over `ephemeral`: a port that survives a reboot is what lets the PROJECT hold its own client config
instead of that config existing only inside a harnessed process.
Not fixed here: 7 links point at catalog paths that no longer exist (beads-team/ became beads/team/,
claude_openbrain-example became openbrain-example, and the omp/claude_time/gstack stacks are gone).
Those need prose judgment about intent, so the tool reports them rather than guessing.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
c75269b
guides/beads: present tense — current behaviour, not how it got here
A user needs to know what the integration does now. The incident narrative,
dates and decision history stay in BEADS.md, which is where a maintainer
looks. Rewritten as 'what you can rely on' with the mechanisms stated in
present tense; setup moved up front.
b7f0b31
guides/beads: lead with the benefit, name all three env-inheritance paths
The value is not 'a database server runs'; it is that bd stops giving
confident wrong answers. Say that first, and note that the shim is
indifferent to which of the three inheritance paths delivered the stale
project.
a6d7d2b
guides/beads: mise env applies to interactive shells; agents rely on the shim
Activation only fires in interactive shells, so mise.local.toml covers a human
in a terminal. Agent-spawned shells, daemon jobs and hooks are covered by the
launch env plus the bd shim instead.
567cba4
guides: add Beads (issue tracking) — the user-facing half of BEADS.md
Written as instructions around the four failures the integration removes:
bd answering about the wrong repo, bd being unconfigured outside the agent,
a connection that goes stale, and harnessed taking ownership of the project's
database credentials. Engineering rationale stays in BEADS.md.
6fabc6c
docs(git-hooks): reframe away from the secret-gate narrative
Pre-existing working-tree change, not authored this session: drops the
two-gates framing, host setup, and traps sections, leaving the generic
hook-resolution guide. _Sidebar.md link text updated to match.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
e8615f2
docs: host-run secrets delivery + git-hooks reframe
secrets.md (this session): document that host-run resolves the same
.env.schema as launch, delivering into os.environ (no temp file), with the
recipe-env-wins / schema-beats-shell precedence rules; fix a stale
'--format env' -> '--format json'; add host-native verification steps.
git-hooks.md + _Sidebar.md: pre-existing working-tree change, not authored
this session — drops the secret-gate narrative for the generic
hook-resolution guide.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
e145560
docs(recipe-authoring): document the rules: field and its flat-vs-nested shape
`rules:` was absent from the recipe.yaml schema block entirely, and the
flat-vs-directory question was undocumented — which led to a standing suspicion
(bd main-oey) that the 8 directory-shaped rules in agent-carnet and
mikes-universal-setup were silently inert in every built image.
They are not. Claude Code's memory docs state that all .md files under
.claude/rules/ are discovered recursively, and any .md filename works, so
.claude/rules/<name>/RULE.md is read exactly like a flat rule.
Add the rules: field to the schema block and a "Rules shape" subsection stating
that both shapes are delivered AND loaded, recommending the flat shape as the
default, and noting the paths: frontmatter and symlink behaviors.
46e45ae
docs(git-hooks): ship hook logic, not wiring — pre-commit is one option, not a requirement
The guide now states the policy (a recipe ships a SCRIPT; wiring is the user's choice; harness hooks
cover the agent) and gives three wirings for the same two scripts: a plain git-hook shim, a
pre-commit repo: local entry, or lefthook/husky.
Also: the 'tracked file' hazard generalized — a hook pointing at a tracked script or config breaks
every commit on a branch that predates it, whether that is a bare exec ("not found") or pre-commit
("No .pre-commit-config.yaml file was found"). Same cure both ways: no-op when the target is absent.
50238a8
secrets: document the credentialed rescan scan (snyk + socket)
The scanner-tokens section documented the opposite of what harnessed now does: it said
a credentialed scan was a manual step you ran yourself (varlock run -- harnessed rescan),
and it named SOCKET_SECURITY_API_KEY, which the Socket CLI does not read.
- build stays credential-free, but now invokes the credentialed pass against the image
it just built, so a normal build does get a full snyk + socket scan.
- harnessed rescan [image] resolves tokens from ~/.config/harnessed/.env{,.schema} and
injects them into a throwaway container.
- canonical Socket var is SOCKET_CLI_API_TOKEN (SOCKET_SECURITY_API_KEY kept as alias);
the org slug is derived from the token, so SOCKET_CLI_ORG_SLUG is not required.
269798e
docs: add git hooks guide; pulumi guide; init contract env; persist $HOME note
guides/git-hooks.md (new) — how git resolves hooks and why tools collide there:
- core.hooksPath (local OR global) makes .git/hooks be IGNORED, not merged
- worktrees share ONE hooks dir ($(git rev-parse --git-common-dir)/hooks)
- pre-commit refuses to install while core.hooksPath is set, and `bd init` sets a local one
- --allow-missing-config is required: the hooks dir is shared across worktrees but
.pre-commit-config.yaml is a tracked file, so a branch predating it fails EVERY commit
- the traps that make a secret gate worse than useless: `id: gitleaks-system` fails OPEN
(no pass_filenames: false -> the filename is eaten as the repo-path arg -> "Passed" on a
live token); a staged-only scan cannot see --no-verify/rebase history; a stage-less hook
"Passes" over 0 bytes at push; conflating a leak with a broken scanner trains you to ignore it
- the two gates: git hooks stop YOU (bypassable with --no-verify); the harness PreToolUse deny
stops the AGENT (not a git hook, so --no-verify cannot reach it)
Also landing work that was sitting uncommitted in the wiki:
- guides/pulumi.md — forwarding the host Pulumi login into the pod
- guides/container-filesystem.md — path-preserving mounts are not $HOME-relative; use $HOST_HOME
- guides/recipe-authoring.md — the init.run contract env table
- _Sidebar.md — link both new guides
899c1eb
docs: add extending-stacks guide; sync aws-sso/egress guides + nav
Add guides/extending-stacks.md — the proposed `extends:` spec for stacks:
single-name inheritance resolved overlay-first, per-field merge table,
`ssh_keys` never inherited, chain-wide staleness hashing, and the hard rule
that a stack declaring a recipe variety cannot be an `extends:` target.
Also lands the pending aws-sso + egress guides and the Home/_Sidebar/
recipe-authoring updates that were sitting uncommitted in the wiki clone.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
06f6471
docs(Home): point removed-from-site links at the wiki
The docs site no longer publishes Research, Codebase map, harnessed-design, or
recipe-build-findings. Repoint Home's links to those at the GitHub wiki so the
site's Home landing has no broken links. The site's link-rewriter handles the
*.md links automatically; the directory links (research/, prompts/) it can't
touch are made absolute here.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
8698667
docs: sync credentials + init/setup guides to current behavior
- container-filesystem.md: split git-credential mounts into always-forwarded
(1P/gpg agent socket + git config, per PR #86) vs opt-in forward_git_credentials
(gh token, private keys, gnupg, YubiKey); fix the contradictory "always
forwarded" note on the ssh-config row. Replace the obsolete Init-markers section
(host-side markers removed — Model A).
- recipe-authoring.md: rewrite init: (no marker; run is sourced inline every
attach and must self-gate) and document the setup: field (summary/reference/
condition) introduced in PRs #77/#79.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ccffdae
secrets: plain .env is now normalized (quotes/export stripped), not passthrough
Reflects the env-file double-quoting fix: a project's plain .env is copied
into a temp env-file with surrounding quotes and export prefixes stripped
(podman --env-file keeps quotes literal), rather than handed to podman as-is.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
b44ec3e
secrets: document per-project env layering over the global schema
Add a "Per-project env" section covering the two per-project sources
(<project>/.env.schema resolved via varlock; plain <project>/.env passed
through) and the [global, project] last-wins precedence, plus a note in
the resolution steps that a project schema resolves like the global one.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
210d638
Document permissions: auto and fix wrong default claim
permissions: was documented as prompt | yolo only; auto (the third
authored value, mapping to acceptEdits — the actual unset default)
was missing, and prompt was wrongly labeled the default.
8dc8803
docs: reconcile maps + roadmap with source (Phase 5 review fixes)
Corrects accuracy defects found in the Phase 5 independent review, each
filed as a bd issue:
- ROADMAP: 15 -> 16 recipes (add repowise); mark main-2nu done (PR #24
merged); scan.py "cbm-verified" -> source-verified (main-1gl)
- STACK.md: fix harnessed-tools subcommand list to match cli.py
(assemble/test/scan/scan-image/scan-image-online/scan-snyk-container/
persist-list/persist-prune); note only claude+omp launchable (main-7yv.1)
- CONCERNS.md: drop void M-5 (both entries now committed); refresh H-1
line/function count; replace drifted launcher.py line citations with
drift-proof symbol refs; point docs/todos refs at bd main-5ki (main-7yv.2)
- INTEGRATIONS.md + ARCHITECTURE.md: mark gemini/codex/opencode/antigravity
planned-unmerged (bd main-9sv); flag serena not capability-verified
(main-7yv.3)
- recipe-catalog.md: add repowise; remove unmerged headroom from a
copy-paste stack; fix superpowers naming note (main-mya)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
4f8b775
docs(prompt): redesign review prompt as a pure in-container agent task
The prompt conflated two audiences (host operator vs in-container agent):
it baked host launch mechanics (--mount-folder, 'relaunch from main/') and
drift-prone hardcodes ('16+' branches, 'host-persisted') into a task the agent
reads AFTER the container is already launched — unactionable from inside.
- add a 'Preconditions' section: tools-live + whole-repo-reachable, framed as
checks the agent runs and reports; unmet = stop and tell the operator, never
relaunch (it can't)
- remove all host launch flags and host-path assumptions; agent discovers its
layout via git worktree list / rev-parse --git-common-dir
- Phase 5: ask the operator to start a fresh session (no --mount-folder flag)
- drop '16+' counts and 'host-persisted' framing; say 'persists across sessions'
- Fallback reframed as the tools-missing branch, keeping the visibility precond
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2ca7265
docs(prompt): update review prompt — stack tools now merged to main
beads/caveman/rtk/codebase-memory-mcp are merged (#12/#14/#15/#16), so the
Starting-context note no longer frames them as unmerged branches — verify as
shipped. The general 'unmerged feat/recipe-* branches' point still stands.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
90fee30
docs: refresh codebase maps, roadmap, and retire todos/ dir
- regenerate codebase/*.md (ARCHITECTURE, STRUCTURE, CONVENTIONS,
INTEGRATIONS, STACK, TESTING, CONCERNS)
- promote todos/ROADMAP.md -> ROADMAP.md
- retire docs/todos/: resolved specs -> done/, reference research -> research/,
obsolete dated dumps removed (dispositions filed as bd issues)
- update Home/_Sidebar, guides (recipe-authoring, recipe-catalog, system-prompt),
harnessed-design, research/*, prompts/ultra-detailed-design-review
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
69b69ce
fixing docs with new findings
5e2e5a4
Add three todos that predate the docs/ migration (hatago-consolidation, startup-hooks, stdio-child-project-access)
201da28
Add grouped sidebar nav matching Home.md sections
1e36765
Replace placeholder Home.md with a real documentation landing page
703e92c