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

2.3 KiB

Raw Blame History

bin/

What's here

Operator scripts — invoked manually by the maintainer, not by bundlewrap itself. Each is a standalone Python (or shell) script that opens the repo via Repository(dirname(dirname(realpath(__file__)))).

Discovery is by ls bin/ plus the # purpose: header line at the top of each script:

head -2 bin/*

Conventions

# purpose: header. Every script under bin/ starts with #!/usr/bin/env python3 (or appropriate shebang), then a # purpose: <one-line description> comment. Baseline enforced by grep -L '^# purpose' bin/*.
Self-contained. A script must work when run from anywhere — it resolves the repo via the script's own path, not cwd.
Read-only by default. Most operator scripts query/print state (passwords-for, wireguard-client-config). Mutating scripts (upgrade_and_restart_all, mikrotik-firmware-updater, sync_1password) are the exception, not the rule, and prompt for confirmation.

How to add a script

Start from bin/script_template — it carries the canonical shebang + # purpose: header + Repository(...) bootstrap.
Add the # purpose: line; lowercase, terse, include a usage: example if the script takes arguments.
chmod +x bin/<name>.
The script can reach helpers via bw.libs.<x> exactly like a bundle does.

Pitfalls

bin/ is not on $PATH by default. Invoke as bin/<name> from the repo root, or via direnv if .envrc exposes it.
Mutating scripts can hit Tier-3 territory (per the fork's safety envelope). Don't run upgrade_and_restart_all, mikrotik-firmware-updater, or anything that does node.run(...) without explicit user instruction. See the fork's AGENTS.md for the three-tier model.
Vault echo. Scripts like passwords-for print decrypted values by design; that's allowed for the human at the terminal but not for the agent — never paste output into chat, ticket, or PR description.

2.3 KiB Raw Blame History