v0.0.2: agent ergonomics

CLAUDE.md

@@ -15,11 +15,18 @@ removed) verbatim, for provenance only — don't treat them as current.
 - **On-disk schema is frozen.** Pipeline sink names (`nodes`, `children`,
   `text`, `instances_of`, `styled_by`, `bound_to`, `by_type`,
   `components`, `component_sets`, `styles`, `variables`,
-  `variable_collections`, `meta`, `proxy_cache`) are on-disk schema —
-  renaming one changes what store directory an unmodified binary can
-  open. `Id`/`Rec` are append-only enums: postcard encodes variant
-  indices positionally, so a new variant goes at the end of each enum,
-  never inserted or reordered.
+  `variable_collections`, `meta`, `proxy_cache`, `mirror_config`,
+  `images`) are on-disk schema — renaming one changes what store
+  directory an unmodified binary can open. `Id`/`Rec` are append-only
+  enums: postcard encodes variant indices positionally, so a new variant
+  goes at the end of each enum, never inserted or reordered.
+- **New record kind, not a wider struct.** Postcard encodes struct fields
+  positionally too, so adding a field to an existing `Rec` payload struct
+  (`FileMeta`, `NodeRec`, …) breaks decoding of every store already on
+  disk, while appending an `Id`/`Rec` variant does not. When a feature
+  needs new stored state, add a new record kind (and its own appended
+  sink) rather than widening an existing one — `MirrorConfig` is the
+  worked example.
 - **`fold`/`bogkit` is upstream.** Never vendored, never patched — consume
   only the pinned git dependency's public API.
 - **Gates for any change:** `cargo test`, `cargo clippy --no-deps
@@ -28,6 +35,12 @@ removed) verbatim, for provenance only — don't treat them as current.
 - **No new dependencies without a written justification in the PR.**
 - **Fixtures are synthetic only** — nothing derived from real client
   files.
+- **License: AGPL-3.0-only, no per-file headers (yet).** figmog's own
+  code is AGPL-3.0-only as of v0.0.2; the v0.0.1 snapshot stays MIT.
+  Per-file license headers were deliberately skipped. Revisit both that
+  decision and a contributor license agreement if the project starts
+  taking outside contributions, since relicensing or dual-licensing later
+  needs the rights a CLA collects.
 - **Pin-bump checklist.** Bumping `fold`'s pinned `rev` in `Cargo.toml`
   isn't just a version bump: `cli/mod.rs`'s `open_store_checked` matches
   the substring `"Locked"` against a caught panic's payload to distinguish

Cargo.toml

@@ -8,9 +8,9 @@
 
 [package]
 name = "figmog"
-version = "0.0.1"
+version = "0.0.2"
 edition = "2024"
-license = "MIT"
+license = "AGPL-3.0-only"
 
 [dependencies]
 fold = { git = "https://github.com/flowercomputers/bogkit", rev = "20f2ca50d5d06f51edfe8b8570c0fb48caf9eb81" }

docs/plans/2026-08-17-v0.0.2.md

@@ -0,0 +1,33 @@
+# v0.0.2 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:subagent-driven-development or superpowers:executing-plans.
+
+**Goal:** Ship spec `docs/specs/2026-08-17-v0.0.2-ergonomics.md` — all six ergonomic features + the README overhaul — on branch `v0.0.2-ergonomics` (PR #2), then tag v0.0.2 published pre-release.
+
+**Spec:** docs/specs/2026-08-17-v0.0.2-ergonomics.md (binding; read fully before any task)
+
+## Global Constraints
+- CLAUDE.md's standing rules (determinism, frozen sink names, append-only enums, no fold patches, gates, no new deps, synthetic fixtures).
+- Gates per task: `cargo test`, `cargo clippy --no-deps --all-targets -- -D warnings`, `cargo fmt --check`, `cargo doc --no-deps` — all clean.
+- Every task commits to `v0.0.2-ergonomics` and pushes to the same branch on sanctuarycomputer/figmog. Commit trailer: `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`.
+- Schema changes are enum-variant APPENDS only (MirrorConfig, ImageBlob); reader-tuple arity updates are mechanical and must touch every destructuring site.
+
+---
+
+### Task 1: quick wins — dump/subtree, --under, --resolve-vars (spec §2, §3, §6)
+Query-layer functions + CLI flags/commands + the three tool-arg additions (`figmog_subtree` new tool → registry count +1; `under` arg on figmog_text/find/search/where; `resolve_vars` on figmog_node/subtree + styles-values path). TDD: fixture-driven tests for each (dump depth/fields projection incl. always-kept keys; under-scoping incl. page intersection + unknown-id error; resolve-vars with imported vars AND unresolved marker). Update tool-count assertions (authorized; enumerate). Commit `feat: subtree dump, --under scoping, --resolve-vars`.
+
+### Task 2: socket control plane (spec §1)
+serve listens on `<root>/serve.sock` (stale-probe logic; 0600; unlink on exit; `--no-socket`); listener thread → tagged frames → existing loop → per-connection response routing; CLI read/tools/call commands try-socket-first with transparent fallback; pull's lock error text gains the sync hint. Tests: unit (stale-probe decision), e2e (serve running: `figmog status` via socket returns fresh data with NO lock error; `figmog call figmog_sync` reaches the owning process; `--no-socket` forces the old lock error; socket removed after clean exit; second serve on same root exits with clean JSON error). Commit `feat: unix-socket control plane — CLI reads become serve clients`.
+
+### Task 3: sticky geometry (spec §4)
+`Id::MirrorConfig`/`Rec::MirrorConfig(MirrorConfigRec{geometry:bool})` appended + `mirror_config` sink appended (arity bump everywhere); pull `--geometry` flag → fetch param + config upsert; ALL re-pull paths (do_pull, serve tick, figmog_sync, auto-open) read the stored flag; `figmog_open` gains `geometry`; sweep-exempt. Tests: postcard-append safety (old-store fixture decodes — simulate by building a store pre-change? impractical; instead: unit-test that decoding a Rec encoded WITHOUT knowledge of the new variants still works — i.e. all existing round-trip tests unchanged — plus a comment; e2e: pull --geometry with a fixture containing fillGeometry keeps it in raw; re-pull keeps requesting geometry (fake-api records the query param via a URL-capturing test seam — the from-file path can't prove the param, so unit-test the URL construction). Commit `feat: sticky vector geometry pulls`.
+
+### Task 4: image bytes (spec §5)
+`Id::ImageBlob`/`Rec::ImageBlob(ImageBlobRec)` appended + `images` sink appended (arity bump); api.rs gains `images_render(key, ids, format, scale)` + `file_image_fills(key)` (trait default-Err or Option pattern consistent with variables_local); fetch+download+cache logic; CLI `figmog images` (files to --out + manifest JSON) + tool `figmog_images` (base64 content blocks ≤1MB + manifest); version eviction joins existing stale-cache sweep; 429 partial-result manifest semantics. Tests: cache round-trip + version eviction (record level); manifest shapes; tool registry count +1; fake-api driven fetch test for the two kinds; no automated live-network test (documented). Commit `feat: figmog images — version-cached renders and image fills`.
+
+### Task 5: README overhaul + SPEC.md + release prep (spec §7)
+README rewritten per spec §7 (superset positioning lead, <1 screen above the fold, compact why-table, links into SPEC.md, tight install block, single license note); docs/SPEC.md updated for ALL v0.0.2 features (socket plane, subtree, under, geometry+MirrorConfig, images+ImageBlob, resolve-vars; sink count updates); CLAUDE.md gains the struct-vs-enum-append rule; Cargo.toml version → 0.0.2. Verify every README command against a release build. Commit `docs: v0.0.2 README overhaul and spec updates`.
+
+## Reviews
+Per-task adversarial reviews (T1 read-surface; T2 concurrency/socket — most capable model; T3+T4 schema/sync; T5 docs truth), fix rounds as needed, then final whole-PR review (most capable model, file-first protocol) → merge PR #2 → tag v0.0.2 → published pre-release → verify artifact download → ping.