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.
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>
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>
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>
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>
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>
Replace placeholder Home.md with a real documentation landing page