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.
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(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.
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
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: 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>
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>
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>