From e1a770612080d3e1a82ef7577df0b085fe14ddf9 Mon Sep 17 00:00:00 2001 From: Chelsea Kelly-Reif <3114598+ChelseaKR@users.noreply.github.com> Date: Sun, 19 Jul 2026 17:54:16 -0700 Subject: [PATCH] docs(readme): visitor-first quickstart + agent docs to CLAUDE.md (DOC-17/18/19) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - DOC-17: replace the '## For Claude Code' README section with a visitor-first '## Quickstart' (make dev demo mode + the real-library ingest commands that already lived in that section) so a quickstart-class heading lands in the first 60 lines. - DOC-18: move the agent contract (build entrypoint, hard guardrails, commands, definition of done) into a new CLAUDE.md; the guardrail/values prose gains a public '## Guardrails' section in the README for human readers. No content lost. - DOC-19: reword the stale '(private) code scanning' comment in scorecard.yml to reflect the repo's public reality (publish_results, id-token: write, and security-events: write were already enabled). Per DOCUMENTATION-STANDARD §9. Co-Authored-By: Claude Fable 5 --- .github/workflows/scorecard.yml | 2 +- CLAUDE.md | 11 ++++++ README.md | 59 ++++++++++++++++++++++++--------- 3 files changed, 55 insertions(+), 17 deletions(-) create mode 100644 CLAUDE.md diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 5076f77..b0e61f3 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -26,7 +26,7 @@ jobs: name: scorecard runs-on: ubuntu-latest permissions: - security-events: write # upload SARIF to (private) code scanning + security-events: write # upload SARIF to this public repo's code scanning id-token: write # sigstore-sign the results file steps: - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..9e80459 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,11 @@ +# CLAUDE.md — queer-the-stacks + +Agent contract for this repository (moved here from the README's "For Claude +Code" section per DOCUMENTATION-STANDARD §9 [DOC-18] — the README is the +visitor's front door). + +- **Build entrypoint:** [`docs/ROADMAP.md`](./docs/ROADMAP.md) → *Implementation Plan*. +- **Hard guardrails:** **open Calibre's `metadata.db` and KOReader's `statistics.sqlite` strictly read-only** (never write to or risk corrupting the real libraries — copy/snapshot before reading); **reading data is sensitive and never leaves the self-hosted instance** (no third-party analytics, no telemetry, behind auth on the seedbox); **do not scrape Goodreads** (Amazon ToS + gatekeeping) — source recommendations from OpenLibrary/Hardcover/Bookwyrm/curated lists with provenance; books and authors are described via *sourced* theme/genre tags, never reductive auto-assigned identity labels; every recommendation shows why + source. +- **Commands:** `make dev` · `make verify` · `make a11y` · `make eval`. +- **Running against a real library:** see the README's [Quickstart](./README.md#quickstart) — real, read-only sources are ingested into the local app-state store via `stacks doctor` / `stacks refresh`; config can also live in `stacks.toml` (`[calibre] path=…`), env vars win. See [`docs/ROADMAP-FUTURE.md`](./docs/ROADMAP-FUTURE.md) for the expansion plan. +- **Definition of done:** a single self-hosted dashboard shows cross-device reading state and stats from Calibre + KOReader, plus explainable recommendations from ethical sources — read-only against source libraries, private to its host, with every repository gate green. diff --git a/README.md b/README.md index da22fcf..678c7a3 100644 --- a/README.md +++ b/README.md @@ -37,22 +37,49 @@ history to a hosted analytics or recommendation service. - **Every pick explained:** why + which source, with diverse/small-press surfacing rather than bestseller bias. - **Self-hosted & private:** runs on your seedbox; reading data never leaves it. -## For Claude Code -- **Build entrypoint:** [`docs/ROADMAP.md`](./docs/ROADMAP.md) → *Implementation Plan*. -- **Hard guardrails:** **open Calibre's `metadata.db` and KOReader's `statistics.sqlite` strictly read-only** (never write to or risk corrupting the real libraries — copy/snapshot before reading); **reading data is sensitive and never leaves the self-hosted instance** (no third-party analytics, no telemetry, behind auth on the seedbox); **do not scrape Goodreads** (Amazon ToS + gatekeeping) — source recommendations from OpenLibrary/Hardcover/Bookwyrm/curated lists with provenance; books and authors are described via *sourced* theme/genre tags, never reductive auto-assigned identity labels; every recommendation shows why + source. -- **Commands:** `make dev` · `make verify` · `make a11y` · `make eval`. -- **Run it on your library:** point it at your real, read-only sources and ingest into the local app-state store — - ```sh - export STACKS_CALIBRE_DB=/path/to/Calibre/metadata.db - export STACKS_KOREADER_DB=/path/to/koreader/statistics.sqlite - # optional cross-device progress (key from the env, never a file): - export STACKS_KOSYNC_HOST=https://sync.koreader.rocks STACKS_KOSYNC_USER=you STACKS_KOSYNC_KEY=… - stacks doctor # validate paths + confirm read-only access (mutates nothing) - stacks refresh # snapshot-first ingest into data/app-state.sqlite - uvicorn app.server:app # serve the dashboard behind auth (set STACKS_AUTH_TOKEN) - ``` - Config can also live in `stacks.toml` (`[calibre] path=…`); env vars win. See [`docs/ROADMAP-FUTURE.md`](./docs/ROADMAP-FUTURE.md) for the expansion plan. -- **Definition of done:** a single self-hosted dashboard shows cross-device reading state and stats from Calibre + KOReader, plus explainable recommendations from ethical sources — read-only against source libraries, private to its host, with every repository gate green. +## Quickstart + +Try it in demo mode first — no real library needed: + +```sh +make dev # installs, then serves a demo dashboard at http://127.0.0.1:8765 +``` + +To run it on your library, point it at your real, read-only sources and ingest +into the local app-state store: + +```sh +export STACKS_CALIBRE_DB=/path/to/Calibre/metadata.db +export STACKS_KOREADER_DB=/path/to/koreader/statistics.sqlite +# optional cross-device progress (key from the env, never a file): +export STACKS_KOSYNC_HOST=https://sync.koreader.rocks STACKS_KOSYNC_USER=you STACKS_KOSYNC_KEY=… +stacks doctor # validate paths + confirm read-only access (mutates nothing) +stacks refresh # snapshot-first ingest into data/app-state.sqlite +uvicorn app.server:app # serve the dashboard behind auth (set STACKS_AUTH_TOKEN) +``` + +Config can also live in `stacks.toml` (`[calibre] path=…`); env vars win. +`make verify` runs every checkable gate (CI parity). See +[`docs/ROADMAP-FUTURE.md`](./docs/ROADMAP-FUTURE.md) for the expansion plan. + +## Guardrails + +- **Source libraries are opened strictly read-only.** Calibre's `metadata.db` + and KOReader's `statistics.sqlite` are never written to or put at risk of + corruption; ingest snapshots/copies before reading. +- **Reading data is sensitive and never leaves the self-hosted instance:** no + third-party analytics, no telemetry, and the dashboard sits behind auth on + its host. +- **No Goodreads scraping** (Amazon ToS + gatekeeping). Recommendations are + sourced from OpenLibrary, Hardcover, Bookwyrm, and curated community lists, + with provenance. +- **Books and authors are described via *sourced* theme/genre tags,** never + reductive auto-assigned identity labels. +- **Every recommendation shows why it was picked and which source it came + from.** + +Agent-facing build instructions (entrypoint, commands, definition of done) live +in [`CLAUDE.md`](./CLAUDE.md). ## Standards Conformance