Skip to content

docs: document every undocumented config key + state file in .crosslink/#590

Merged
dollspace-gay merged 3 commits into
developfrom
docs/582-hook-config-missing-keys
May 11, 2026
Merged

docs: document every undocumented config key + state file in .crosslink/#590
dollspace-gay merged 3 commits into
developfrom
docs/582-hook-config-missing-keys

Conversation

@dollspace-gay
Copy link
Copy Markdown

@dollspace-gay dollspace-gay commented May 11, 2026

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:

  • 5 keys into ## Fields: tracker_remote, external-cache-ttl, external-url-ttl, repo-alias, sandbox.command
  • New ## Agent overrides section with agent_overrides.{tracking_mode, blocked_git_commands, gated_git_commands, agent_lint_commands, agent_test_commands}
  • New ## Sentinel configuration section with 13 keys grouped under top-level / sources / default_agent / escalation

Plus a "Local sandbox alternative" subsection in docs_src/guides/container-agents.qmd cross-linked to the new sandbox.command entry.

Commit 2 — additional 7 keys (940a1d14)

Found by greping every config.get(...) / config[...] site in src/ and .claude/hooks/:

  • 5 keys in a new ## Watchdog configuration section: watchdog.{enabled, staleness_secs, max_nudges, check_interval_secs, grace_period_secs} (read by read_watchdog_config in kickoff/launch.rs)
  • crosslink_binary and context_budget_chars appended 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.qmd covering every remaining file in .crosslink/:

  • hook-config.local.json — per-developer overlay
  • agent.json — machine-local agent identity (all 7 fields)
  • locks.json — coordination lock file including the previously-undocumented settings.stale_lock_timeout_minutes
  • swarm.toml — trust model configuration ([trust] / [ignore] / [boundaries] tables)
  • session.json — daemon-flushed session state mirror

Plus 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 from hook-config.qmd to 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.qmd after 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

  • All key/default values cross-checked against the source-of-truth: config_registry.rs, resources/crosslink/hook-config.json, src/identity.rs, src/locks.rs, src/trust_model.rs, src/daemon.rs, WatchdogConfig::default() in kickoff/types.rs
  • Cross-links between hook-config.qmd and state-files.qmd use explicit anchors for any dotted-key target
  • _quarto.yml navbar + sidebar both register the new page
  • Render the quarto site locally (or rely on the CI docs build) to verify the new page lands and all anchors resolve

🤖 Generated with Claude Code

dollspace-gay and others added 3 commits May 11, 2026 13:39
…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>
@dollspace-gay dollspace-gay self-assigned this May 11, 2026
@dollspace-gay dollspace-gay merged commit 3ac702e into develop May 11, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(hook-config): missing config keys not documented in reference/hook-config.qmd

1 participant