docs: project init — CLAUDE.md, README, OpenSpec store binding #1

Merged

synapse merged 8 commits from docs/init into develop

2026-08-21 00:38:06 +00:00

synapse commented

2026-08-21 00:37:09 +00:00

Owner

Project initialization: docs and planning wiring, no code yet.

CLAUDE.md: architecture overview, decided vs. open design constraints, OpenSpec store binding, fj CLI how-to (incl. the SSH-port host-derivation gotcha)
README: full problem statement — why a gateway instead of GoatCounter's native public-site toggle
OpenSpec: repo bound to the dedicated store goatcounter-stats-gateway via a store-pointer openspec/config.yaml; repo-local planning root removed (it shadowed the store)
Beads scaffold from bd init

The first change (dev-environment: flake, devshell with local seedable GoatCounter, walking skeleton, NixOS VM check) lives in the store and is ready for /opsx:apply after this merges.

🤖 Generated with Claude Code

https://claude.ai/code/session_01T5j3dAJVcUjZv9k76sRTt9

Project initialization: docs and planning wiring, no code yet. - CLAUDE.md: architecture overview, decided vs. open design constraints, OpenSpec store binding, fj CLI how-to (incl. the SSH-port host-derivation gotcha) - README: full problem statement — why a gateway instead of GoatCounter's native public-site toggle - OpenSpec: repo bound to the dedicated store `goatcounter-stats-gateway` via a store-pointer `openspec/config.yaml`; repo-local planning root removed (it shadowed the store) - Beads scaffold from bd init The first change (`dev-environment`: flake, devshell with local seedable GoatCounter, walking skeleton, NixOS VM check) lives in the store and is ready for /opsx:apply after this merges. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01T5j3dAJVcUjZv9k76sRTt9

synapse added 8 commits

2026-08-21 00:37:09 +00:00

docs: Beads init 318a1b77b2

docs: Init OS 880d8902ad

docs: fill in CLAUDE.md and README 51a2716c58

CLAUDE.md: architecture overview, decided/open design constraints,
honest Build & Test state, OpenSpec design workflow section.
README: full problem statement and how-it-works.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T5j3dAJVcUjZv9k76sRTt9

spec: dev-environment — first OpenSpec change e03074aa98

Flake-based dev env as the project's ground: devshell with a real local
seedable GoatCounter (nixpkgs 2.7.0), walking-skeleton axum binary
(/healthz only), crane packaging, nixosModules.default as chiba's
consumption contract, and a NixOS VM integration test running both
services together. All five stats-API design questions stay open for
the next change.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T5j3dAJVcUjZv9k76sRTt9

chore: move OpenSpec to dedicated store, drop repo-local root 282c575a92

The dev-environment change and openspec root now live in the registered
store 'goatcounter-stats-gateway' (~/openspec/goatcounter-stats-gateway).
A repo-local openspec/ shadows the store during root resolution, so it
must not exist here; CLAUDE.md now says to always pass --store.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T5j3dAJVcUjZv9k76sRTt9

docs: README no longer points at removed openspec/ dir 70161fd722

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T5j3dAJVcUjZv9k76sRTt9

chore: bind repo to openspec store via store pointer 4f84c182f3

openspec/config.yaml carries only `store: goatcounter-stats-gateway`, so
commands run in-repo resolve to the dedicated store without --store.
Caveat kept in CLAUDE.md: any specs/ or changes/ dir here (even empty)
counts as planning shape and shadows the pointer — that's what bit us.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T5j3dAJVcUjZv9k76sRTt9

docs: fj CLI how-to in CLAUDE.md 90ebed830c

Documents the host-derivation gotcha (SSH port 23491 leaks into the API
URL, so -H git.byteflavour.dev is mandatory), auth setup, and the PR
commands agents should use on this Forgejo.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T5j3dAJVcUjZv9k76sRTt9

synapse merged commit 943d221ca6 into develop

2026-08-21 00:38:06 +00:00

synapse deleted branch docs/init

2026-08-21 00:38:06 +00:00

synapse referenced this pull request from a commit

2026-08-21 00:38:07 +00:00

Merge pull request 'docs: project init — CLAUDE.md, README, OpenSpec store binding' (#1) from docs/init into develop

synapse referenced this pull request

2026-08-21 00:42:36 +00:00

docs: fj auth keyring gotcha — -H required on add-token too #2