tangled
The gh equivalent for tangled.org
Star 1
Fork 0
Watch

docs: mark every writing command as writing; skill show/install + generated reference #14

Merged pipobscure.com
targeting main from feature/skill-and-write-marking
Merged opened by and assigned to pipobscure.com
targeting main from feature/skill-and-write-marking

Companion to the atcli and dns changes (PR #1 in each): every writing command is now marked as writing in every document an agent might read, and the agent skill ships as a first-class artifact — bundled with the binary.

What #

  • writes?: false | 'network' | 'local' on the Command interface; every runnable command (105) classified: 50 network / 13 local / 42 reads. Network = state on tangled/knots/spindles or public records (repo create/delete/edit/rename/sync/star, collaborator grants, issue & pr mutations incl. merge, run trigger/cancel, release upload/delete-file, string/secret/user/ssh-key mutations, knot/spindle registration and membership, api). Local = durable machine state only (auth login/logout/switch, setup-git, repo clone/remote, pr checkout, config, alias, shell --install, skill install). Reads = everything else; caches (completion cache, last-check stamp, knots.json) and downloads are treated as incidental reads, not writes.
  • New generated skills/tangled/reference.md (from the command tree via src/reference.ts + tools/reference.ts --check): marker under each writing command's summary, a "Which commands write" section up top, and an exhaustiveness check — the generator refuses to run while any runnable command lacks the declaration. The xrpc-style caveat is generalized into a small CAVEATS map, used for tangled api and both label commands (usage-dependent writeness, marked network as the safe direction). Two new tests: reference currency + a tree-walk that every runnable command declares writes.
  • New tangled skill show / skill install command (src/commands/skill.ts): show prints the guide, or guide + generated reference as one document (--brief for guide only); install writes .claude/skills/tangled/ (project or --global). The git-credential-tangled busybox path in src/cli.ts is untouched.
  • tools/manifest.ts updated so the bundle actually ships skills/tangled/ and observes the new skill runs.
  • README.md gains a What writes section.

Judgment calls (flagged for review) #

  • auth logout = local although it also revokes the server-side session — mirrors atcli's logout; the doc line says it "ends the session and forgets the tokens".
  • repo remote = local (rewrites this checkout's remotes/config); a caveat could be added if agents should be warned about overwriting existing remotes.
  • tangled shell = local wholesale though bare shell bash only prints — mirrors atcli's completion treatment; the skill table scopes the write to --install/--uninstall.
  • tangled's Command has no default field, so bare tangled skill prints help; show/install are explicit.

Tests #

  • tsc -p . --noEmit clean; node --test 13/13 pass.
  • tools/reference.ts --check passes; npm run build + npm run manifest verified (47 members, all observed reads covered).
  • Smoke-tested offline only: no real knot/atproto calls, no auth, no push.
Commits 0