cronekorkn/bundlewrap
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
bundlewrap/docs/agents/commands.md
CroneKorkN 04558a9189
docs: scaffold agent-friendly entry points (Phase 1) 
introduces a balanced set of agent + human docs:

- root AGENTS.md (with CLAUDE.md symlink) — 5-rule quickstart,
  layout map, mental model, use-case keyed example pointers.
- docs/agents/conventions.md — vault/demagify, eval-loader
  constraints, group inheritance, naming, do-not-touch list,
  suspension idioms, working-style notes.
- docs/agents/commands.md — repo-specific deltas to the fork's
  bw runbook (apt-key offline-verify, *.py_ suspended-node
  visibility, vault-echo rule).
- per-area AGENTS.md for bundles/, nodes/, groups/, libs/,
  hooks/, data/, items/, bin/ — mechanism-focused, no enumeration.
- bundles/AGENTS.template.md — per-bundle doc template with
  optional `## Writes into` section for cross-namespace reactors.

bundlewrap-language reference (item types, dep keywords, reactors,
runbook, three-tier safety envelope) is not duplicated here; we
link out to the fork's AGENTS.md instead.

bw test still green. all internal links resolve. Phase 0 invariants
preserved (libs/hooks docstrings, bin/* # purpose: headers).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-10 15:44:45 +02:00

1.8 KiB
Raw Blame History

Commands

The canonical bw-command runbook — read-only allowlist, three-tier safety envelope, after-change table, hash-diff workflow, bw debug sketch — lives in the fork's AGENTS.md. Read that first.

This file collects only the deltas specific to ckn-bw.

Apt-key changes need offline verification

Editing files under data/apt/keys/*.{asc,gpg} rotates a signing key the whole apt subsystem trusts. Trial-and-error with bw apply is the failure path: a wrong key blocks unattended upgrades cluster-wide until corrected manually.

Before touching data/apt/keys/:

  1. Fetch the new key from its upstream source (project release page, keys.openpgp.org, etc.).
  2. gpg --show-keys <newkey> — print the fingerprint.
  3. Diff against the fingerprint published by the upstream source.
  4. Only after the fingerprint matches, place the file under data/apt/keys/ and let bundles/apt consume it on the next apply.

*.py_ suspended nodes are invisible to bw nodes

The repo loader (nodes.py) only matches files ending in .py. Files ending in .py_ are silently skipped. If bw nodes reports a node missing, check whether its file has been parked:

ls nodes/ | grep '\.py_$'

This is the suspension idiom, not a bug.

Vault output never leaves the terminal

The fork's runbook calls out that bw debug resolves vault magic strings transparently. In ckn-bw specifically: never echo, log, or paste decrypted values, even from a bw debug -c one-liner. If you need to verify a secret resolved correctly, hash or fingerprint it instead.

See conventions.md#secrets for the demagify magic-string list and the rule's full rationale.