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: 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>
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.
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>
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>
fixing docs with new findings
Import docs/ from the harnessed repo (2026-07-02)
Mirrors the repo's docs/ tree structure (codebase/, guides/, todos/,
research/, done/, prompts/) as the initial wiki content. Source repo
will reference this wiki as a git submodule at docs/.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>