From 4d06f528358116212255e65ac96ee0fbca84abb3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yoaquim=20Cintr=C3=B3n?= Date: Sun, 26 Apr 2026 10:42:59 -0400 Subject: [PATCH] Update README and CLAUDE.md with landing page, project structure, practices README: - Add website link under title - Add stage-people, seed-people, landing/, people-pending to project structure - Remove stale test count CLAUDE.md: - Add landing page to stack and structure - Add seed-people.py, landing/ to structure - Add format/format:check commands - Add generic-speakers.txt config - Add squash merge policy - Add landing/docs exclusion note --- CLAUDE.md | 12 ++++++++++-- README.md | 18 +++++++++++++----- 2 files changed, 23 insertions(+), 7 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 62cde86..36bbb37 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,9 +7,10 @@ Open-source Pocket AI companion — pulls recordings via API, analyzes with Clau - **Dashboard**: React + TypeScript + Vite + Tailwind v4 + shadcn/ui (base-ui) - **Mind maps**: @xyflow/react (React Flow) - **Pull script**: Python 3 (stdlib only, no deps) -- **Orchestration**: Bash +- **Orchestration**: Bash (xargs -P for parallelism) - **Analysis**: Headless Claude Code - **API server**: Express (TypeScript) +- **Landing page**: Vite + React + Magic UI + shadcn/ui (separate app in `landing/`) ## Project structure @@ -17,9 +18,11 @@ Open-source Pocket AI companion — pulls recordings via API, analyzes with Clau - `scripts/pocket-run.sh` — orchestration: pull → analyze (5 parallel) → stage people → rebuild manifest - `scripts/build-manifest.py` — aggregates all recordings + analyses into `public/manifest.json` - `scripts/stage-people.py` — scans analyses for speaker names, stages for user review +- `scripts/seed-people.py` — seeds people.json from existing analyses (contributed via PR) - `prompts/analyze.md` — prompt template for Claude analysis (includes speaker inference) - `server/index.ts` — Express API (sync, people, pending people, actions, speakers, delete) - `src/` — React dashboard +- `landing/` — landing page (separate Vite app, builds to `docs/landing/`, deployed via GitHub Pages) - `.seam/` — local data directory (gitignored) ## Commands @@ -29,12 +32,16 @@ Open-source Pocket AI companion — pulls recordings via API, analyzes with Clau - `npm test` — run all tests (vitest + pytest) - `npm run test:ts` — TypeScript tests only - `npm run test:py` — Python tests only +- `npm run lint` — ESLint +- `npm run format` — Prettier (write) +- `npm run format:check` — Prettier (check only) - `./scripts/pocket-run.sh` — full sync (pull + analyze + rebuild) ## Config - `.env` — `POCKET_API_KEY=pk_xxx` - `.pocket-last-sync` — timestamp of last successful sync (auto-managed) +- `.seam/generic-speakers.txt` — user-defined speaker exclusion list (one per line) ## Practices @@ -84,10 +91,11 @@ Tests must pass before committing. No feature code without tests. ### Git -- No direct pushes to main — PRs only +- No direct pushes to main — PRs only, squash merge - **NEVER use `--no-verify`** — pre-commit hooks exist to catch issues before CI - Pre-commit hook (husky) runs: `format:check` → `lint` → `test` - **Before every commit**, verify locally: `npm run format:check && npm run lint && npm test` - If any of these fail, fix them before committing — do not bypass - Branches: `feature/`, `fix/`, `chore/` - Commit messages: imperative, describe the "what" and "why" +- `landing/` and `docs/landing/` are excluded from root prettier and eslint (separate project) diff --git a/README.md b/README.md index 0ba873b..2d84ea2 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,10 @@ Pull your recordings via the API, analyze them with Claude, and browse everything in a local dashboard — no Pro subscription needed.

+

+ Website · GitHub +

+ ## Screenshots | Home | Summary | Actions | @@ -115,18 +119,22 @@ After each sync, `stage-people.py` scans analysis results for new speaker names ``` seam/ ├── scripts/ -│ ├── pocket_pull.py # Pulls recordings from Pocket API -│ ├── pocket-run.sh # Orchestration: pull → analyze (5 parallel) → rebuild -│ └── build-manifest.py # Aggregates data for the dashboard +│ ├── pocket_pull.py # Pulls recordings from Pocket API (with retry + pending-fetch) +│ ├── pocket-run.sh # Orchestration: pull → analyze (5 parallel) → stage people → rebuild +│ ├── build-manifest.py # Aggregates data for the dashboard +│ ├── stage-people.py # Stages inferred speakers for review +│ └── seed-people.py # Seeds people from existing analyses ├── prompts/ │ └── analyze.md # Claude analysis prompt template ├── server/ -│ └── index.ts # Express API (sync, people, actions, speakers, delete) +│ └── index.ts # Express API (sync, people, pending people, actions, speakers, delete) ├── src/ # React dashboard +├── landing/ # Landing page (separate Vite app, deployed to GitHub Pages) ├── .seam/ # Local data (gitignored, created on first sync) │ ├── recordings/ # Structured recording data │ ├── analysis/ # Claude analysis output │ ├── people.json # Known people registry +│ ├── people-pending.json # Staged speakers awaiting review │ └── sync-history.json # Sync run history └── .env.example ``` @@ -134,7 +142,7 @@ seam/ ## Tests ```bash -npm test # Runs vitest (TS) + pytest (Python) — 52 tests +npm test # Runs vitest (TS) + pytest (Python) npm run test:ts # TypeScript only npm run test:py # Python only ```