feat(cloud): Phase 5 — Supabase cloud sync for team wiki sharing

[nmrtn]

Vision

nanopm's wiki is the shared PM memory of a product — opportunities, personas, decisions, strategy. Until now it lived only on your machine. This PR makes it a team asset.

The architecture is local-first: every write lands on disk first (fast, offline-safe). Supabase is a sync layer on top — push after every write, pull at startup. If Supabase goes down, nanopm keeps working; you're just back to git-based sharing until it comes back.

Three modes, one clean model:

• Solo — local only, wiki tracked in git
• Small team — git sharing (previous PR feat: wiki team sharing — git tracking, SQLite FTS5 search, companies/ deprecation, compact index #171)
• Team — this PR: Supabase as the sync bus, automatic push/pull, no merge conflicts

What this PR does

Schema

Two migrations:

• 001_nanopm_wiki.sql — nanopm_wiki_pages (one row per page, upserted on every write), nanopm_wiki_log (team activity log, mirrored after every skill run), nanopm_projects (project registry). pgvector extension enabled for future semantic search. RLS enabled with the publishable key.
• 002_nanopm_raw.sql — nanopm_raw_sources (one row per raw source file, upserted on sync). Same RLS policy.

Raw source sync

.nanopm/raw/ — the content-addressed archive of feedback, interviews, and competitor intel that everything else is derived from — is now synced alongside the wiki. Includes competitors/snapshots/ so teammates get the diff baseline and don't see "BASELINE" results on their next intel run. Same hand-edit protection as wiki pages: hash-diverged files are skipped on pull with a warning.

Automatic push

Every nanopm-ingest-agent apply (the locked wiki page writer) now upserts to Supabase immediately after the local write — best-effort, silent on failure. Local write never blocks.

Automatic pull

nanopm_pull_from_supabase() runs in nanopm_preamble on every skill start, throttled to once per 10 minutes. Fetches pages updated on Supabase since the last pull. Newest wins on conflict (last_updated comparison); local wins on tie. After a fresh clone or a teammate's sync, context is up to date before the skill runs.

Hand-edit protection

After every push or pull, sha256(content) is recorded per page in ~/.nanopm/sync-state/{project}.json. On the next pull, if a local file's hash has diverged from the stored baseline (hand edit), it is skipped rather than silently overwritten — with a message: "local edits detected — run 'sync' to push your changes first.".

Sync visibility

nanopm-ingest-agent status shows which local pages and raw sources have been modified since the last sync — offline, no Supabase call. Reports: N in sync · M modified locally · K never synced for both wiki and raw.

Bulk commands

• nanopm-ingest-agent sync — push all local wiki pages and raw sources (initial setup, force-resync)
• nanopm-ingest-agent pull — pull all remote pages and raw sources
• nanopm-ingest-agent status — show local sync state for wiki and raw (offline)

Credentials

Stored in ~/.nanopm/.env — never in the repo, never in the chat. Format:

NANOPM_SUPABASE_URL=https://YOUR-PROJECT-REF.supabase.co
NANOPM_SUPABASE_KEY=sb_publishable_YOUR-KEY

Resolution order: env vars → .env file. The publishable key (sb_publishable_...) is correct here — RLS is enabled.

/pm-setup-cloud skill

Interactive onboarding: detects existing config, shows instructions to write ~/.nanopm/.env in the terminal (never in chat), verifies credentials without printing them, runs the migration via Supabase MCP if available, does the initial sync.

Security

cmd_pull and cmd_raw_pull now validate every path field received from Supabase against a relative_to() guard before writing — ensuring a tampered row can't write outside .nanopm/wiki/ or .nanopm/raw/. Same pattern already in cmd_push_file.

What's next (Phase 5.5)

• --force flag on pull to bypass hash check (clean overwrite from a teammate)
• pgvector semantic search (replace SQLite FTS5 when Supabase is configured)
• JWT-scoped RLS (per-user access control instead of permissive allow-all)
• Web viewer (read-only dashboard for stakeholders without the CLI)

---

For Guillaume — how to sync

One-time setup:

1. Pull this branch (or wait for it to merge to main):

   git pull && git checkout feat/supabase-cloud-sync
   ./setup

2. Get the Supabase URL + publishable key from Nicolas (out of band — Slack, 1Password, etc.)

3. Create ~/.nanopm/.env in your terminal:

   cat > ~/.nanopm/.env << 'EOF'
   NANOPM_SUPABASE_URL=https://YOUR-PROJECT-REF.supabase.co
   NANOPM_SUPABASE_KEY=sb_publishable_YOUR-KEY
   EOF

4. Push your wiki and raw sources to Supabase (coordinate with Nicolas first):

   nanopm-ingest-agent --project . sync

5. Nicolas then runs:

   nanopm-ingest-agent --project . pull

From then on, everything is automatic — push happens after every wiki write, pull happens at the start of each skill run.

🤖 Generated with Claude Code

[nmrtn]

Rebased on the updated #171 (which now gitignores derived files).

One cascading fix here: cmd_sync previously pushed everything including index.md, log.md, and INDEX/LOG/SCHEMA files — which are now gitignored and derived. Added SKIP_ON_SYNC to exclude them. Only source entity pages and doc pages get pushed to Supabase. Team log history goes through the nanopm_wiki_log table, not file sync.

[nmrtn]

Fixed a gap in the auto-push coverage.

What was missing: the PR description said "push happens after every wiki write" but that was only true for entity pages written via nanopm-ingest-agent apply (which already called _supabase_upsert_page). Doc pages — retro, PRD, roadmap, competitors, feedback, personas, etc. — are written directly by skills using the Write tool and were silently skipped. They only reached Supabase via a manual nanopm-ingest-agent sync.

Fix (ea21f07):

• New push-file --target <wiki-relative-path> subcommand in nanopm-ingest-agent: reads the file from disk, security-checks it stays inside wiki/, upserts to Supabase.
• nanopm_wiki_doc_log now calls push-file after the log heartbeat. Every skill already calls this function as its last step after writing a wiki page — so all 20+ skills get the push with zero skill-file changes.
• The path is extracted from the title arg by stripping the leading verb: "wrote docs/retro-2026-07-02.md" → "docs/retro-2026-07-02.md".
• Entity pages pushed twice (via apply + via doc_log) — idempotent upsert, no problem.
• Best-effort throughout: silent no-op when Supabase isn't configured, silent on failure.

The "everything is automatic" line in the PR description is now actually true.

[guillaumesimon]

Went through the PR — really nice work, and I'm glad the wiki finally becomes something we share. Quick note on format: I reviewed this with Claude. The plain-English intro on each point is mine; the technical detail underneath is generated by Claude.

1. We could lose a manual edit without noticing

If I tweak a page by hand and the cloud has a newer version, mine can get quietly overwritten — no warning, no trace. Fine if we always go through the skills, but I'd like a guardrail.

cmd_pull (bin/nanopm-ingest-agent) writes pages with dest.write_text(...) without taking wiki_lock — unlike cmd_apply/cmd_reindex — and it runs in nanopm_preamble on every skill start. A hand-edited page whose last_updated wasn't bumped gets silently replaced by a newer remote, plus there's a small race with a concurrent apply. Suggest wrapping the write in wiki_lock and logging overwritten pages. Minor: the PR says "remote wins on conflict" but the code is actually "newest wins, local wins on a tie."

2. One thing the description promises isn't wired up yet

The PR says the team activity log is shared through the cloud, but as far as I can tell it isn't — only page content syncs. Mostly want to make sure we don't assume it's live when it isn't.

The migration creates nanopm_wiki_pages, nanopm_wiki_log and nanopm_projects, but only nanopm_wiki_pages is ever upserted. The "Fix D" commit says team log history goes through nanopm_wiki_log, yet nothing writes to it. Either wire up the log mirror, or drop the two unused tables from the MVP and adjust the wording so it matches what ships.

3. A few small finishing touches (non-blocking)

Nothing here blocks it — mostly polish plus one Git housekeeping item.

• Blocking network calls: cmd_pull uses timeout=10 inside the preamble, per-page push uses timeout=5 × N pages — a noticeable stall at skill start on a slow connection; maybe ~2–3s for the pull.
• cmd_sync's "not configured" error still points to supabase_url in ~/.nanopm/config; since the .env switch it should reference NANOPM_SUPABASE_URL in ~/.nanopm/.env.
• PR base is feat/wiki-search-team-sharing, but feat: wiki team sharing — git tracking, SQLite FTS5 search, companies/ deprecation, compact index #171 is already merged to main — re-point to main for a clean merge.
• Tiny/optional: unused project param in _supabase_creds, redundant import argparse in cmd_pull, synced_at not refreshed on upsert, and SKIP_ON_SYNC lives only in cmd_sync (not the auto-push path).

[guillaumesimon]

Following up on my own review — I'd also like us to sync the raw sources, not just the wiki.

To me the raw content (archived feedback, interview transcripts, etc.) is at least as important as the wiki pages — arguably more, since it's the ground truth everything else is derived from. If the whole point of Phase 5 is that our shared PM memory lives in one place, then a fresh clone (or anyone relying on the cloud) is missing half of it without the raw. I'd love to bring .nanopm/raw/ into the sync — can we scope that, either in this PR or a fast follow-up?

Technical detail (from Claude):
Raw isn't covered by any sync path today: cmd_apply refuses targets outside .nanopm/wiki/, so the auto-push never sees it, and cmd_sync only globs .nanopm/wiki/**/*.md. Raw lives in .nanopm/raw/<type>/<id>.* — a sibling dir, and not necessarily Markdown. Bringing it in would likely mean a dedicated table (e.g. nanopm_raw_sources) plus a separate push path that handles arbitrary file types, reusing the existing content-hash dedup (raw-check / nanopm_archive_raw, 12-hex sha256 id) so identical sources aren't re-uploaded. Worth deciding how large transcripts are handled (size limits).

[nmrtn]

Addressed all three points — here's what changed:

Point 1 — hand-edit protection (now implemented, not just noted)
After every push or pull, sha256(content) is stored per page in ~/.nanopm/sync-state/{project}.json. On the next pull, if the local hash has diverged from the stored baseline, the file is skipped with a message instead of silently overwritten. The PR description's "remote wins on conflict" is corrected to "newest wins; local wins on tie".

Point 2 — nanopm_wiki_log wired
cmd_log now calls _supabase_log_entry() after the local write — a POST to nanopm_wiki_log with project_slug, op, title, day. Same best-effort pattern as page upserts. Team activity log now actually reaches Supabase as the PR claimed.

Point 3 — error message + base branch
cmd_sync "not configured" error now references NANOPM_SUPABASE_URL / NANOPM_SUPABASE_KEY in ~/.nanopm/.env. PR base re-pointed to main.

Bonus — status subcommand
nanopm-ingest-agent status reports local sync state offline (no Supabase call): N in sync · M modified locally · K never synced, with file-level detail for the modified ones. Useful before pushing or after a pull to confirm where things stand.

The wiki_lock concern in cmd_pull is valid — deferred to a follow-up PR as it's a narrow race window.

[nmrtn]

working on raw content sync now. I'll let you know when ready.

[nmrtn]

Raw sync is in — commit d045510.

Everything under .nanopm/raw/ is now synced: feedback archives, manifests, interview transcripts, competitor intel reports, events.jsonl, and competitors/snapshots/ (included so you get the diff baseline and don't see "BASELINE" results on your next intel run).

sync and pull handle everything — no change to how you use them.