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 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