docs: document every undocumented config key + state file in .crosslink/#590
Merged
Merged
Conversation
…H#582)
Closes the gap reported in GH#582: 11 of the 30+ keys crosslink reads
from `.crosslink/hook-config.json` were documented in
`docs_src/reference/hook-config.qmd`. This commit adds the remaining 19
following the existing per-key format (key, type, default, 1-3
sentences). Defaults are sourced from `resources/crosslink/hook-config.json`
and the registry descriptions in `src/commands/config_registry.rs`.
## Changes
- `docs_src/reference/hook-config.qmd`:
- Appended 5 entries to `## Fields`: `tracker_remote`,
`external-cache-ttl`, `external-url-ttl`, `repo-alias`,
`sandbox.command` (with an explicit `{#sandbox-command}` anchor for
bulletproof cross-linking).
- New `## Agent overrides` section with 5 sub-keys
(`agent_overrides.tracking_mode`, `.blocked_git_commands`,
`.gated_git_commands`, `.agent_lint_commands`, `.agent_test_commands`)
plus an intro paragraph explaining the agent/human policy split.
- New `## Sentinel configuration` section with 13 sub-keys grouped
under top-level / sources / default_agent / escalation, including
a JSON example matching the embedded default.
- `docs_src/guides/container-agents.qmd`:
- New `### Local sandbox alternative` subsection in `## Why containers?`
introducing `sandbox.command` for users who can't run Docker/Podman,
cross-linked back to the hook-config reference.
Pure documentation change — no code surface touched, no behavioral
change, no new tests required.
Note: `read_watchdog_config` in `kickoff/launch.rs` reads 5 more keys
directly from hook-config.json (`watchdog.enabled`, `staleness_secs`,
`max_nudges`, `check_interval_secs`, `grace_period_secs`). These are
the same kind of gap but weren't in the issue's enumerated list of 19,
so they're intentionally out of scope here — suitable for a follow-up
issue if desired.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…get_chars keys (#731, GH#582) Follow-up to the initial GH#582 sweep — the previous commit covered the 19 keys enumerated in the issue but left 7 more undocumented: - 5 `watchdog.*` keys read by `read_watchdog_config` in `kickoff/launch.rs`: `enabled`, `staleness_secs`, `max_nudges`, `check_interval_secs`, `grace_period_secs`. Defaults sourced from `WatchdogConfig::default()` in `kickoff/types.rs`. Added as a new `## Watchdog configuration` section between Agent overrides and Sentinel configuration, including the canonical JSON block. - `crosslink_binary` (read by `.claude/hooks/crosslink_config.py`) and `context_budget_chars` (read by `prompt-guard.py`). Added to `## Fields` after `repo-alias` since both are simple top-level infrastructure keys. Exhaustive coverage verified by greping every `config.get(...)` and `config[...]` call site in `src/` and `.claude/hooks/`. The only remaining lookalike — `stale_lock_timeout_minutes` — lives in `locks.json`, not `hook-config.json`, so it's out of scope here. Total documented keys in `hook-config.qmd` after both commits: 37, up from the 11 baseline. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
….crosslink/ file (#731, GH#582)
Per follow-up scope expansion: document everything undocumented, not
just hook-config.json keys. Adds a new
`docs_src/reference/state-files.qmd` page covering every other file
crosslink reads from `.crosslink/`, registered in both navbar and
sidebar via `_quarto.yml`.
## Files documented
- **hook-config.local.json** -- per-developer overlay (same schema as
`hook-config.json`, shallow-merged on top, gitignored). Explains
`crosslink config set --local` and why it survives `init --force`.
- **agent.json** -- machine-local agent identity. Documents all 7
fields of `AgentConfig` (`agent_id`, `machine_id`, `description`,
`role`, `ssh_key_path`, `ssh_fingerprint`, `ssh_public_key`) sourced
from `src/identity.rs`.
- **locks.json** -- coordination lock file. Documents `version`,
`locks.<issue_id>.{agent_id,branch,claimed_at,signed_by}`, and the
one user-tunable knob `settings.stale_lock_timeout_minutes` (default
60) sourced from `src/locks.rs`.
- **swarm.toml** -- trust model configuration. Documents the three
TOML tables (`[trust]`, `[ignore]`, `[boundaries]`) and their fields
sourced from `src/trust_model.rs`.
- **session.json** -- daemon-flushed session state mirror. Documents
`session_id`, `started_at`, `active_issue_id` sourced from the
flush payload in `src/daemon.rs`.
Plus a closing "Other files" table briefly explaining 14 internal
state items (issues.db, daemon/sentinel logs+pids, driver-key.pub,
heartbeats/, keys/, last_test_run, repo-id, promotion-log.json,
.gitignore, the four caches, rules/, and the meta/orchestrator/locks
subsystem dirs) so users know they exist and aren't meant for editing.
## Cross-links
- `hook-config.qmd` now points at the new
`state-files.qmd#hook-config-local-json` for the overlay schema.
- Explicit `{#sentinel-enabled}` anchor added in `hook-config.qmd`
and `{#hook-config-local-json}` in the new page, so cross-links
through dotted-key headings remain stable regardless of Pandoc's
identifier rules.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes GH#582 and the follow-up scope expansion. The original issue listed 19 undocumented keys in
.crosslink/hook-config.json; this PR documents those plus every other undocumented key crosslink reads, plus every other user-editable file in.crosslink/.Commit 1 — original 19 hook-config keys (
73345d5c)Appended to
docs_src/reference/hook-config.qmd:## Fields:tracker_remote,external-cache-ttl,external-url-ttl,repo-alias,sandbox.command## Agent overridessection withagent_overrides.{tracking_mode, blocked_git_commands, gated_git_commands, agent_lint_commands, agent_test_commands}## Sentinel configurationsection with 13 keys grouped under top-level / sources / default_agent / escalationPlus a "Local sandbox alternative" subsection in
docs_src/guides/container-agents.qmdcross-linked to the newsandbox.commandentry.Commit 2 — additional 7 keys (
940a1d14)Found by greping every
config.get(...)/config[...]site insrc/and.claude/hooks/:## Watchdog configurationsection:watchdog.{enabled, staleness_secs, max_nudges, check_interval_secs, grace_period_secs}(read byread_watchdog_configinkickoff/launch.rs)crosslink_binaryandcontext_budget_charsappended to## Fields(read by the Python hooks)Commit 3 — new state-files reference page (
6c3df2d4)Per the user's expanded directive ("document everything undocumented, nothing is out of scope"), added
docs_src/reference/state-files.qmdcovering every remaining file in.crosslink/:settings.stale_lock_timeout_minutesPlus a closing table briefly acknowledging 14 internal state items (databases, logs, PIDs, caches, keys, subsystem dirs) so they're not invisible.
Registered the new page in both navbar and sidebar via
_quarto.yml. Cross-link fromhook-config.qmdto the overlay file. Explicit{#sentinel-enabled}and{#hook-config-local-json}anchors so cross-references through dotted-key headings stay stable.Coverage
Documented keys in
hook-config.qmdafter this PR: 37, up from the 11 baseline (verified exhaustive by grep). New state-files page documents 5 user-editable files with full schemas plus an internal-state table covering the rest.Test plan
config_registry.rs,resources/crosslink/hook-config.json,src/identity.rs,src/locks.rs,src/trust_model.rs,src/daemon.rs,WatchdogConfig::default()inkickoff/types.rshook-config.qmdandstate-files.qmduse explicit anchors for any dotted-key target_quarto.ymlnavbar + sidebar both register the new page🤖 Generated with Claude Code