pocketsync 0.10.0__tar.gz → 0.10.1__tar.gz

{pocketsync-0.10.0 → pocketsync-0.10.1}/AGENTS.colleague.md

@@ -1,9 +1,9 @@
 # Colleague Resident — `pocketsync`
 
-You are a colleague session working in a clone of this template — reading
+You are a colleague session working in the pocketsync repo — reading
 this file because colleague's prompt cascade resolves it here, not because
 `culture.yaml` selected you. That declaration says `backend: claude`, so
-`CLAUDE.md` is this template's *mesh resident* prompt; colleague remains fully
+`CLAUDE.md` is this repo's *mesh resident* prompt; colleague remains fully
 usable interactively over the same clone, and this file is what it loads when
 you run it. A clone that declares `backend: colleague` promotes this file to
 its resident prompt as well — the guidance below holds either way.
@@ -31,13 +31,20 @@ update this section so the docs keep matching what's actually on disk.
 
 ## What this project is
 
-`pocketsync` is a clonable template for AgentCulture mesh agents —
-an agent-first CLI, a mesh identity, the canonical skill kit, and a
-buildable/deployable package baseline. `CLAUDE.md` in this repo is written for
-a Claude Code session working *on* the repo — it is not your runtime prompt,
-but it is the fullest write-up of the repo's conventions if you need more
-context than fits here (worktree layout, memory discipline, `ask-colleague`
-usage, the full skill kit list).
+`pocketsync` is the **sync bridge for the Pocket AI voice recorder**. It
+pulls recordings, transcripts (STT), summaries and action items out of
+Pocket's cloud into local disk and/or S3. That landing zone (a per-recording
+directory layout plus an append-only `events.jsonl`) is the contract
+[`culture-rules`](https://github.com/agentculture/culture-rules) consumes.
+pocketsync never routes data further.
+
+**Status: scaffold only.** The sync engine is *(planned)*; the build brief is
+[issue #1](https://github.com/agentculture/pocketsync/issues/1). `CLAUDE.md`
+is written for a Claude Code session working *on* the repo. It is not your
+runtime prompt, but it is the fullest write-up of the planned architecture,
+the CLI contract and the repo's conventions (worktree layout, memory
+discipline, `ask-colleague` usage). Read it when a task needs more context
+than fits here.
 
 ## How you work
 
@@ -49,3 +56,9 @@ usage, the full skill kit list).
   (see `docs/skill-sources.md` for the re-sync procedure).
 - Every PR bumps the version (`version-bump` skill) — CI's `version-check` job
   blocks merge otherwise.
+- The repo is public: never commit tokens, recordings, transcripts or
+  fixtures made from real recordings. Tests run against a fake Pocket adapter
+  and a fake S3, with synthetic fixtures.
+- Keep the CLI contract: `--json` on every verb, results to stdout and errors
+  to stderr, `CliError` for failures, and an `explain` catalog entry for each
+  new verb. Write verbs are dry-run by default and commit with `--apply`.

{pocketsync-0.10.0 → pocketsync-0.10.1}/AGENTS.override.md

@@ -20,14 +20,29 @@ what the repo is and how it is laid out, not who is reading it.
 
 ## What this project is
 
-`pocketsync` is a clonable template for AgentCulture mesh agents —
-a working, minimal example of the sibling pattern every Culture agent follows:
-an agent-first CLI, a mesh identity, the canonical skill kit, and a
-buildable/deployable package baseline. It is a sibling to
-[`guildmaster`](https://github.com/agentculture/guildmaster) (the skills
-supplier), [`steward`](https://github.com/agentculture/steward) (alignment),
-and [`teken`](https://github.com/agentculture/teken) (the CLI scaffolder this
-package is cited from).
+`pocketsync` is the **sync bridge for the Pocket AI voice recorder**
+(<https://heypocket.com>). It pulls recordings, speech-to-text transcripts,
+summaries and action items out of Pocket's cloud into a store we own: local
+disk and/or S3. [`culture-rules`](https://github.com/agentculture/culture-rules)
+workflows route the data onward from that landing zone, so its layout and the
+append-only `events.jsonl` handoff stream are a public contract (draft schema
+in `README.md`).
+
+**Status: scaffold only.** The repo is still the `culture-agent-template`
+scaffold renamed to `pocketsync`. The sync engine, Pocket adapter, sinks and
+events are *(planned)*, and none of that code exists yet. The build brief is
+[issue #1](https://github.com/agentculture/pocketsync/issues/1). Its first
+open question is whether Pocket can be accessed at all: no official API is
+known, and the community approach uses a reverse-engineered API with an
+hourly-expiring Firebase token. If you are asked about Pocket API access,
+report what is verified and what is not.
+
+Siblings: [`guildmaster`](https://github.com/agentculture/guildmaster)
+(skills supplier), [`steward`](https://github.com/agentculture/steward)
+(alignment), [`teken`](https://github.com/agentculture/teken) (the CLI
+scaffolder this package is cited from), `culture-rules` (the downstream
+consumer), and [`events-cli`](https://github.com/agentculture/events-cli)
+(the optional MQTT event bus).
 
 ## Four harnesses, four files, no shared base
 
@@ -57,7 +72,7 @@ agents:
   backend: claude
 ```
 
-This template's *mesh* resident runs on `backend: claude`, so `CLAUDE.md` is
+This repo's *mesh* resident runs on `backend: claude`, so `CLAUDE.md` is
 the live resident prompt. A Pi session working in a clone of this repo is a
 **local tool session**, not the mesh resident — it reads this file and
 `.pi/SYSTEM.md` regardless of what `culture.yaml` declares, and running `pi`
@@ -65,18 +80,19 @@ here neither requires nor changes that declaration.
 
 (A clone that wants `associate` as its *mesh* resident declares
 `backend: colleague` with `model: associate` — see `docs/skill-sources.md`.
-That is a per-clone choice; this template does not ship it.)
+That is a per-clone choice; this repo does not ship it.)
 
 ## Layout (what you can read/find/summarize here)
 
 ```text
-pocketsync/   agent-first CLI (cited from teken's python-cli reference)
+pocketsync/               agent-first CLI (cited from teken's python-cli reference)
   cli/                    parser, error/output contract, _commands/ (verbs)
   explain/                markdown catalog for `explain`
 tests/                    pytest smoke + introspection tests
+scripts/                  scan-secrets.py, harness-smoke.py (CI gates)
 .claude/skills/           vendored guildmaster skill kit (cite-don't-import)
-docs/skill-sources.md     skill provenance ledger
-culture.yaml              mesh identity (suffix + backend)
+docs/                     skill provenance, harness selection/automation contract
+culture.yaml              mesh identity (suffix + backend) + gate commands
 .github/workflows/        tests + deploy (PyPI Trusted Publishing)
 ```
 
@@ -85,9 +101,11 @@ culture.yaml              mesh identity (suffix + backend)
 - The vendored skills under `.claude/skills/` are cited **verbatim** from
   guildmaster — never propose editing their scripts; the fix belongs upstream
   (`docs/skill-sources.md` has the re-sync procedure).
-- The package/CLI name (`pocketsync` / `pocketsync`)
-  is hard-coded in roughly a hundred places; a rename is a `git grep` sweep,
-  not a hand edit (see `CLAUDE.md`'s "Cloning this template" section).
+- The repo is public. Never quote, copy or summarize real Pocket
+  credentials, recordings or transcripts into anything that could be
+  committed; test fixtures are synthetic by rule.
+- Write verbs (planned) are dry-run by default and commit only with
+  `--apply`, so a dry-run is the safe way to answer "what would sync do?".
 - Every PR bumps the version (`version-bump` skill); CI's `version-check` job
   blocks merge otherwise.
 - This file describes the repo **as it exists on disk today**. If you are

{pocketsync-0.10.0 → pocketsync-0.10.1}/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.1] - 2026-10-14
+
+### Changed
+
+- `CLAUDE.md` re-initialized from the seed into a full runtime prompt for the Pocket sync agent: the domain and lane, the issue #1 build brief and its verify-the-API-first premise, the planned adapter/sink/events architecture (marked planned), the CLI contract, the CI gates, and the repo conventions.
+- `README.md` now describes pocketsync rather than the template: the lane and non-goals, the planned CLI verbs, and a draft landing-zone layout and `events.jsonl` handoff contract for culture-rules, plus a credentials and privacy section.
+- `QWEN.md`, `AGENTS.override.md` and `AGENTS.colleague.md` updated to the same project description and status.
+- `learn`, `explain`, `overview` and `--help` now describe the Pocket sync purpose instead of the template; `overview` names `CLAUDE.md` (not `AGENTS.colleague.md`) as the identity prompt.
+
 ## [0.10.0] - 2026-10-06
 
 ### Added

pocketsync-0.10.1/CLAUDE.md

@@ -0,0 +1,236 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this project is
+
+`pocketsync` is the **sync bridge for the Pocket AI voice recorder**
+(<https://heypocket.com>). Pocket records audio and produces speech-to-text
+transcripts, summaries and action items in **its own cloud**. pocketsync pulls
+that data out into a store we own — **local disk** and/or **S3** (or any
+S3-compatible bucket) — and stops there.
+
+That landing zone is the whole lane. Fan-out to Notion, the mesh, email,
+eidetic memory and so on is the job of
+[`culture-rules`](https://github.com/agentculture/culture-rules) workflows,
+which trigger on pocketsync's output. So the output layout and the event
+stream are a **public contract** other code builds against; treat changes to
+them like API changes.
+
+Non-goals (from the build brief): no re-running STT (Pocket's transcript is
+the source of truth; at most we store the audio), no routing to downstream
+destinations, no UI.
+
+## Status — scaffold only, build brief is issue #1
+
+As of the last update to this file, the repo is still the
+`culture-agent-template` scaffold renamed to `pocketsync`. **No Pocket, sink,
+sync or event code exists yet.** The only verbs on disk are the agent-first
+identity/introspection verbs (`whoami`, `learn`, `explain`, `overview`,
+`doctor`, `cli overview`).
+
+[Issue #1](https://github.com/agentculture/pocketsync/issues/1) is the build
+brief and the requirements baseline. Read it before designing anything.
+`gh issue view 1` fails on the deprecated Projects-classic field, so use:
+
+```bash
+gh issue view 1 --repo agentculture/pocketsync --json title,body,comments
+```
+
+**Verify the API premise first.** guildmaster found no official Pocket
+developer API or bulk export. The only known path is a community skill that
+reads `app.heypocket.com` through a **reverse-engineered** API, authenticated
+with a **Firebase ID token** from a logged-in browser session. That token
+expires about every hour. The first deliverable in #1 is a report on:
+
+- any official API, webhook, integration (Zapier, Notion, …) or export;
+- whether a Firebase **refresh token** can be persisted so sync runs
+  unattended;
+- Terms-of-Service limits on automated access. Flag them; don't ignore them.
+
+Prefer an official path, even a narrow one, if one exists.
+
+For new feature work the vendored devague chain applies: `/scope` → `/think`
+→ `/challenge` (optional) → `/spec-to-plan` → `/assign-to-workforce` (or
+build directly).
+
+## Target architecture (planned — from #1, adjust once reality is verified)
+
+None of this exists yet. It's the shape the brief asks for, so new code should
+slot into it rather than invent a parallel one.
+
+- **Source adapter: Pocket**, behind an interface. List recordings since a
+  cursor. Fetch each recording's transcript (with speakers and timestamps if
+  available), summary, action items and metadata, plus the audio behind a
+  flag because it's large. The Pocket API is unofficial and *will* break, so
+  nothing outside the adapter may depend on its wire format. Tests use a
+  **fake Pocket adapter**.
+- **Sink adapters: `local` and `s3`**, behind one interface so more can be
+  added. Proposed per-recording layout:
+  `<root>/<YYYY>/<MM>/<recording-id>/{meta.json, transcript.json, transcript.md, summary.md, audio.*}`.
+  Writes are **atomic, with `meta.json` written last**, so a reader that sees
+  `meta.json` never sees a half-written recording. S3 uses the standard AWS
+  credential chain (env, profile or role) and no bespoke secret store. Tests
+  use a **fake S3** (moto or a stub).
+- **Incremental, idempotent sync.** Persisted cursor/state. A re-run with no
+  remote changes is a no-op. Pocket may re-process a transcript or summary, so
+  updates are detected by **content hash** and re-synced.
+- **Handoff contract: `events.jsonl`.** An append-only file in the sink root
+  with one event per new or updated recording, carrying the recording id, sink
+  paths, content hash and `created`/`updated`. A hook or MQTT publish via
+  [`events-cli`](https://github.com/agentculture/events-cli) is an optional
+  addition. The schema is documented in `README.md` and is what culture-rules
+  builds against. #1 also asks for one example culture-rules rule that
+  consumes it.
+- **CLI verbs**: `auth` (set up and verify credentials), `list` (remote
+  recordings plus sync status), `sync [--to local|s3] [--since …]
+  [--with-audio] [--apply]`, `watch` (poll loop or daemon), `status` (cursor,
+  last run, errors). **Write verbs are dry-run by default and commit only with
+  `--apply`**, and every verb takes `--json`.
+
+Runtime dependencies are currently **zero** (`dependencies = []`). A
+third-party client such as `boto3` should go behind an optional extra (for
+example `pocketsync[s3]`) and be imported lazily, so the core and the
+`local` sink stay dependency-free. Test-only libraries such as `moto` go in
+the `dev` dependency group.
+
+## Constraints that bite
+
+- **This repo is public.** Never commit tokens, recordings, transcripts, or
+  fixtures derived from real recordings. Test fixtures are **synthetic**.
+  Credentials live in env vars, the keyring or a git-ignored config.
+- **`scripts/scan-secrets.py` runs in CI** (lint job). It flags token-shaped
+  strings and secret-ish `key = value` assignments in any tracked file. It
+  also flags **non-localhost URLs under `url`/`host`/`endpoint`/`baseUrl`
+  keys in any file that parses as JSON**. A Pocket base URL in Python source
+  is fine. The same URL in a committed JSON fixture or config fails CI, so
+  synthetic JSON fixtures should use `localhost` or omit URL keys.
+- PyPI/TestPyPI Trusted Publishing for `pocketsync` still has to be
+  registered by the operator. Until then the publish jobs in
+  `.github/workflows/publish.yml` fail on the PyPI side, which is expected.
+
+## Commands
+
+```bash
+uv sync                                      # install (incl. dev group)
+uv run pytest -n auto                        # full suite (what culture.yaml's gate runs)
+uv run pytest tests/test_cli.py::test_whoami_json -v   # a single test
+uv run pytest -n auto --cov=pocketsync --cov-report=term   # with coverage (fail_under = 60)
+
+uv run black pocketsync tests && uv run isort pocketsync tests   # format (line length 100)
+uv run flake8 pocketsync tests
+uv run bandit -c pyproject.toml -r pocketsync
+markdownlint-cli2 "**/*.md" "#node_modules" "#.local" "#.claude/skills" "#.teken"
+python3 scripts/scan-secrets.py              # CI secret/endpoint gate
+uv run teken cli doctor . --strict           # agent-first rubric gate (CI)
+uv run python scripts/harness-smoke.py --stage config   # four-harness config check (CI)
+
+uv run pocketsync --help                     # the CLI
+```
+
+CI (`.github/workflows/tests.yml`) runs: `test` (pytest with coverage, plus
+the SonarCloud scan when `SONAR_TOKEN` is set), `lint` (all of the lint
+commands above), `harness-smoke`, and on PRs `version-check`.
+
+## How the CLI is built
+
+The CLI is cited (cite-don't-import) from teken's `python-cli` reference.
+Read several files together to see the contract:
+
+- **Registration.** Each verb or noun is a module in
+  `pocketsync/cli/_commands/` exposing `register(sub)`. It is wired in by
+  hand in `_build_parser()` in `pocketsync/cli/__init__.py`. Handlers return
+  `None`/`int`, or raise `CliError`.
+- **Error contract.** Every failure raises `CliError(code, message,
+  remediation)` from `pocketsync/cli/_errors.py`. `_dispatch()` wraps any
+  other exception into one, so no traceback ever reaches the user.
+  `_CliArgumentParser` routes argparse errors through the same path. It scans
+  raw argv for `--json` *before* parsing, so even parse errors render as JSON.
+  Exit codes: `0` success, `1` user error, `2` environment error, `3+`
+  reserved.
+- **Output contract.** `pocketsync/cli/_output.py`: results go to stdout via
+  `emit_result`, and errors and diagnostics go to stderr via `emit_error` /
+  `emit_diagnostic`. Never mix them. Text-mode errors print `error:` plus a
+  `hint:` line, which the rubric requires.
+- **`explain` catalog.** `pocketsync/explain/catalog.py` maps command-path
+  tuples to markdown. Every new verb or noun needs an entry, and
+  `tests/test_cli.py` checks that every catalog path resolves. When adding
+  verbs, also update `learn.py` (text and JSON command map) and the `_VERBS`
+  list in `overview.py`.
+- **Rubric.** `teken cli doctor . --strict` enforces things like `--json` on
+  every command, `learn` content, and any noun with action verbs exposing
+  `overview` (that's why the `cli` noun exists). Planned nouns must keep it
+  green.
+- **Identity.** `whoami`/`doctor` find `culture.yaml` by walking up from
+  the module file (not the cwd) and parse it without a YAML dependency. In a
+  wheel install there is no `culture.yaml`, so `doctor` reports a single info
+  check and exits 0.
+
+## Identity and the four harness prompt files
+
+`culture.yaml` declares `suffix: pocketsync`, `backend: claude`, so **this
+file is the mesh resident prompt**. `pocketsync doctor` and `steward doctor`
+check **prompt-file-present** and **backend-consistency** (`claude` ↔
+`CLAUDE.md`).
+
+There are four harnesses, each reading exactly one root prompt, with
+deliberately **no shared `AGENTS.md`**. `harness-smoke.py` fails CI if a bare
+`AGENTS.md` appears.
+
+| Harness | File(s) |
+|---------|---------|
+| Claude Code | `CLAUDE.md` (this file) |
+| Pi / associate | `AGENTS.override.md` (context) + `.pi/SYSTEM.md` (system prompt) |
+| colleague | `AGENTS.colleague.md` |
+| Qwen Code | `QWEN.md` |
+
+When the project's description or state changes, **update all four, not just
+this one**. The other three summarize this file and must not drift. The live
+harness probes in `docs/harness-invocations.yaml` assert on file content:
+
+- Claude and Qwen are asked whether their file "describes this project as
+  pocketsync";
+- Pi is asked about the lobes-cli `associate` attribution, which must stay in
+  `.pi/SYSTEM.md` only.
+
+`culture.yaml` selects only the *mesh resident*; all four harnesses stay
+usable interactively (see `docs/harness-selection.md`).
+
+The `gate` section of `culture.yaml` (`uv sync`, then `uv run pytest -n
+auto`) is how external tooling sets up and tests this repo. Keep it accurate
+if the setup or test command changes.
+
+## Conventions
+
+- **Every PR bumps the version**, even docs, config or CI: use the
+  `version-bump` skill, which updates `pyproject.toml` and `CHANGELOG.md`.
+  The `version-check` CI job blocks merge otherwise. `__version__` is read
+  from package metadata, so `pyproject.toml` is the single source.
+- **PRs go through the `cicd` skill** (`devex pr` plus SonarCloud gating;
+  needs `devex` on PATH). Posts are signed `- pocketsync (Claude)`. The
+  `cicd`/`communicate` scripts append that automatically from
+  `culture.yaml`, so don't sign bodies they post.
+- **Vendored skills are cited verbatim.** Don't reformat or edit anything
+  under `.claude/skills/`. Fixes go upstream, then re-sync per
+  `docs/skill-sources.md`. `.qwen/skills`, `.pi/skills` and
+  `.colleague/skills` are symlinks to `.claude/skills`, and tests enforce
+  that.
+- **Reach for `ask-colleague` reflexively.** Run `review` on a non-trivial
+  committed diff before opening a PR, and `explore` for a fresh read of an
+  unfamiliar area. Both are read-only, in a throwaway worktree. `write
+  --apply` / `write --pr` need the user's go-ahead. Treat its output as a
+  second opinion to verify, not authority.
+- **Worktrees you create go in `../.worktrees.pocketsync/<name>/`** with a
+  work-scoped branch prefix (`sync/sinks`, not `agent/t2`). The vendored
+  `assign-to-workforce` skill's example uses `../worktrees/` and
+  `agent/<task-id>`; override both. Remove a worktree with `git worktree
+  remove`. `ask-colleague`'s own temporary worktrees under `$TMPDIR` are
+  exempt, because they clean themselves up.
+- **Memory: `/recall` before, `/remember` after.** The wrappers default to
+  scope `pocketsync` with `--visibility public`, which lands records in the
+  committed in-repo store `.eidetic/memory/`. Use `--visibility private` for
+  anything that must stay in `$HOME`, which includes anything about
+  credentials or real recordings. Store decisions and gotchas, not what the
+  repo already records.
+- Keep docs grounded in what is on disk. Mark anything not yet built as
+  *(planned)*, as this file does.

pocketsync-0.10.1/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: pocketsync
+Version: 0.10.1
+Summary: Sync Pocket voice-recorder recordings, transcripts (STT) and summaries from the Pocket cloud to local disk or S3 - a durable landing zone that culture-rules workflows fan out to anywhere.
+Project-URL: Homepage, https://github.com/agentculture/pocketsync
+Project-URL: Issues, https://github.com/agentculture/pocketsync/issues
+Author: AgentCulture
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# pocketsync
+
+Sync Pocket voice-recorder recordings, transcripts (STT) and summaries from the
+Pocket cloud to local disk or S3 - a durable landing zone that culture-rules
+workflows fan out to anywhere.
+
+## What it does
+
+[Pocket](https://heypocket.com) records audio and produces transcripts,
+summaries and action items in its own cloud. pocketsync copies that data into
+a store you own:
+
+- **local disk** (a directory tree), and/or
+- **S3** (or any S3-compatible bucket).
+
+That is the whole job. pocketsync does not send the data anywhere else.
+[`culture-rules`](https://github.com/agentculture/culture-rules) workflows
+pick it up from the landing zone and route it onward (Notion, the Culture
+mesh, email, eidetic memory, …). The landing-zone layout and the event stream
+below are the stable contract they build against.
+
+Non-goals: re-running speech-to-text (Pocket's transcript is the source of
+truth), routing data downstream, and any UI.
+
+## Status
+
+**Early: the sync engine is not built yet.** Today the package is the
+agent-first CLI scaffold (identity and introspection verbs only). The build
+brief is [issue #1](https://github.com/agentculture/pocketsync/issues/1).
+
+**Pocket API access is unverified.** No official Pocket developer API or bulk
+export has been found so far. The known community approach uses a
+reverse-engineered `app.heypocket.com` API with a short-lived (about one hour)
+Firebase ID token. Before the sync engine is built, issue #1 calls for a
+report on:
+
+- whether an official path exists;
+- whether authentication can persist unattended;
+- what Pocket's Terms of Service say about automated access.
+
+## Planned CLI
+
+Write verbs are dry-run by default and commit only with `--apply`. Every verb
+takes `--json`.
+
+| Verb | What it will do |
+|------|-----------------|
+| `pocketsync auth` | Set up and verify Pocket credentials. |
+| `pocketsync list` | List remote recordings and their sync status. |
+| `pocketsync sync [--to local\|s3] [--since …] [--with-audio] [--apply]` | Incrementally sync recordings into a sink. |
+| `pocketsync watch` | Poll loop or daemon around `sync`. |
+| `pocketsync status` | Show the cursor, the last run and errors. |
+
+Sync is incremental and idempotent. A persisted cursor means a re-run with no
+remote changes does nothing. A content hash detects when Pocket re-processes a
+transcript or summary, and that recording is re-synced.
+
+## Landing-zone contract (draft)
+
+> **Draft.** This is the shape proposed in issue #1. It is not implemented
+> yet and may change before the first release that writes data. Once
+> released, changes to it are breaking changes for culture-rules consumers.
+
+### Layout
+
+One directory per recording, in the same layout on local disk and on S3:
+
+```text
+<root>/
+  events.jsonl                     # append-only handoff log (below)
+  <YYYY>/<MM>/<recording-id>/
+    meta.json                      # manifest — written LAST
+    transcript.json                # speakers + timestamps where available
+    transcript.md
+    summary.md
+    audio.*                        # only with --with-audio
+```
+
+Every file is written atomically, and `meta.json` is written last. A consumer
+that sees `meta.json` can rely on the rest of the recording being complete.
+
+### `events.jsonl`
+
+One JSON object per line, appended for each recording that is new or has
+changed. Each event carries at least:
+
+| Field | Meaning |
+|-------|---------|
+| recording id | Pocket's identifier for the recording. |
+| sink paths | Where the recording's files landed. |
+| content hash | Hash of the synced content; a new hash means an update. |
+| `created` / `updated` | Timestamps for the recording / this sync. |
+
+The exact field names will be fixed in this README when the sync engine
+ships. Optionally, the same events may also be published over MQTT via
+[`events-cli`](https://github.com/agentculture/events-cli).
+
+## Credentials and privacy
+
+This repository is public. Pocket credentials belong in environment variables,
+the OS keyring, or a git-ignored config file. They are never committed. S3
+access uses the standard AWS credential chain (environment, profile or
+instance role). Tests use a fake Pocket adapter, a fake S3, and synthetic
+fixtures only, never data from real recordings.
+
+## Quickstart (development)
+
+```bash
+uv sync
+uv run pytest -n auto                 # run the test suite
+uv run pocketsync whoami              # identity from culture.yaml
+uv run pocketsync learn               # self-teaching prompt (add --json)
+uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
+```
+
+## CLI available today
+
+| Verb | What it does |
+|------|--------------|
+| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
+| `learn` | Print a structured self-teaching prompt. |
+| `explain <path>` | Markdown docs for any noun/verb path. |
+| `overview` | Read-only descriptive snapshot of the agent. |
+| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
+| `cli overview` | Describe the CLI surface itself. |
+
+Every command supports `--json`. Results go to stdout, errors/diagnostics to
+stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
+error, `3+` reserved.
+
+## As a Culture mesh agent
+
+pocketsync is also an AgentCulture mesh agent, provisioned from
+`culture-agent-template`:
+
+- **A mesh identity**: `culture.yaml` (`suffix: pocketsync`,
+  `backend: claude`) and the matching resident prompt, `CLAUDE.md`.
+- **The guildmaster skill kit** under `.claude/skills/`, vendored
+  cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
+- **CI and deploy**: pytest, lint, a secret scan, the agent-first rubric
+  gate, a four-harness smoke check, and PyPI Trusted Publishing.
+
+### Prompt files by harness
+
+Four harnesses, four root files, no shared base. Each file is read by exactly
+one harness:
+
+| Harness | File(s) |
+|---------|---------|
+| Claude Code | [`CLAUDE.md`](CLAUDE.md) |
+| Pi / associate | [`AGENTS.override.md`](AGENTS.override.md) + [`.pi/SYSTEM.md`](.pi/SYSTEM.md) |
+| colleague | [`AGENTS.colleague.md`](AGENTS.colleague.md) |
+| Qwen Code | [`QWEN.md`](QWEN.md) |
+
+`CLAUDE.md` is the fullest write-up of the repo's conventions; read it first.
+There is intentionally **no `AGENTS.md`**, because a shared base would leak
+Claude-specific guidance into the other harnesses.
+
+`culture.yaml`'s `backend` selects only the **mesh resident**, the one prompt
+the Culture daemon loads. It does not limit which harness you can run
+interactively in the clone; all four stay live. See
+[`docs/harness-selection.md`](docs/harness-selection.md) and
+[`docs/automation-contract.md`](docs/automation-contract.md).
+
+### The `gate` section
+
+`culture.yaml` carries a top-level `gate` section that declares how to set up
+and test this repo, so tooling (for example a PR-fixer that re-runs the checks
+before pushing) needs no per-repo knowledge:
+
+```yaml
+gate:
+  setup:
+  - [uv, sync]
+  test:
+  - [uv, run, pytest, -n, auto]
+```
+
+`setup` and `test` are each a list of commands, and each command is an argv
+list (never a shell string), run in order from the repo root. Culture's loader
+ignores unknown top-level keys, so the section is safe alongside `agents`.
+
+## License
+
+Apache 2.0 — see [`LICENSE`](LICENSE).