Sharing ARCIVE docs

How to share, read, and discuss the docs in this repo with the team and with AI chat tools (Claude, ChatGPT, Gemini). Lives next to README.md — keep this file short and operational.

The source of truth is the markdown files in this folder and decisions/ / discussions/. Two sanctioned mirrors render the same content for different audiences — see Source-of-truth split below. Don’t create a third copy by hand.

Sending a doc to a teammate (chat link)

Paste the GitHub URL. GitHub renders markdown beautifully and respects relative links between docs.

ADRs: https://github.com/arcive-io/arcive.io/blob/master/docs/decisions/0011-ai-vendor-strategy.md
Discussions: https://github.com/arcive-io/arcive.io/blob/master/docs/discussions/2026-05-05_ai_strategy_architecture.md
Plans: https://github.com/arcive-io/arcive.io/blob/master/docs/01_SOFTWARE_PLAN.md

For deep links to a specific section: click the section heading on the rendered page; GitHub adds #section-name to the URL. That URL works as a chat-share link.

For citing at a specific point in time (e.g., “the version we agreed to last week”): hit y on a GitHub page to get a permalink that pins the commit SHA. Useful in PR descriptions and decision threads.

Calling Edge Functions from your terminal

Supabase Edge Functions need both apikey and Authorization headers when using the new sb_secret_* key format (legacy JWTs accept either alone — sending both works for both formats).

PowerShell:

$SUPABASE_URL = "https://<your-project-ref>.supabase.co"
$KEY = "<paste your sb_secret_* or service_role JWT here, single line>"
$headers = @{
  "apikey"        = $KEY
  "Authorization" = "Bearer $KEY"
  "Content-Type"  = "application/json"
}
$body = @{ batch_size = 100; dry_run = $true } | ConvertTo-Json -Compress

Invoke-RestMethod -Method Post `
  -Uri "$SUPABASE_URL/functions/v1/<function-name>" `
  -Headers $headers `
  -Body $body

bash / zsh:

curl -X POST "$SUPABASE_URL/functions/v1/<function-name>" \
  -H "apikey: $KEY" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"batch_size": 100, "dry_run": true}'

For one-shot operations like the summarize backfill, prefer the SQL Editor in the Supabase dashboard — no auth headers, no PowerShell quoting hell:

SELECT pgmq.send(
  'pipeline_jobs',
  jsonb_build_object('step', 'summarize', 'recording_id', recording_id),
  0
)
FROM memories
WHERE (summary IS NULL OR topics IS NULL)
  AND transcript IS NOT NULL AND transcript <> ''
  AND recording_id IS NOT NULL
LIMIT 500;

pipeline-tick (every 30s) drains the queue automatically.

Pasting a doc into Claude / ChatGPT / Gemini

Three ways, ordered by convenience:

1. Paste the raw GitHub URL (preferred for Claude)

Claude can fetch raw GitHub URLs directly. Copy the rendered URL, swap /blob/ for /raw/, paste:

https://github.com/arcive-io/arcive.io/raw/master/docs/decisions/0011-ai-vendor-strategy.md

Or just say “read this doc and tell me X: ” — Claude usually fetches it. ChatGPT may need the /raw/ form.

2. Copy the markdown locally

From the repo on your machine:

# macOS
cat docs/decisions/0011-ai-vendor-strategy.md | pbcopy

# Windows (PowerShell)
Get-Content docs/decisions/0011-ai-vendor-strategy.md | Set-Clipboard

# Linux (xclip)
cat docs/decisions/0011-ai-vendor-strategy.md | xclip -selection clipboard

Then paste into the chat. Self-contained, works in every AI tool.

3. Copy from GitHub’s “Raw” view

On any rendered doc page, click Raw (top-right of the file viewer). Select all, copy, paste. Works without a local clone.

Reading docs offline / in your editor

The markdown files render natively in:

VS Code — open the docs/ folder; press Ctrl/Cmd+Shift+V on any .md file for split-pane preview. Cross-doc links work.
Obsidian — add this repo as a vault (point Obsidian at the repo root or just at docs/). Gives you graph view across all linked docs, fuzzy search, and a clean reading layout. Read-only is fine; don’t edit through Obsidian unless you also commit the changes.
GitHub Mobile app — repo browser renders markdown. Useful for cofounder catch-up on the move.
Plain cat in a terminal — markdown is human-readable as-is for short docs.

How docs are organized (where to look)

docs/
├── README.md                  ← index of everything
├── SHARING.md                 ← this file
├── 00_MASTER_PLAN.md          ← product thesis, principles, roadmap
├── 01_SOFTWARE_PLAN.md        ← software architecture (incl. §1.4 AI layer model)
├── 02_HARDWARE_PLAN.md        ← hardware architecture
├── 03_PROGRESS.md             ← living status — currently shipping, next up, backlog
├── 04_JOURNAL.md              ← chronological narrative of the build
├── decisions/                 ← ADRs (numbered, immutable once accepted)
│   ├── README.md              ← ADR index
│   ├── 0001-...md ... 0011-...md
│   └── template.md
└── discussions/               ← working session notes (exploratory, not committed plans)
    ├── 2026-05-04_multimodal_expansion.md
    └── 2026-05-05_ai_strategy_architecture.md

Quick triage if you don’t know where to look:

You want to know…	Read
Why we made some choice	`decisions/` — search by keyword
What’s the AI architecture	`01_SOFTWARE_PLAN.md §1.4` → `decisions/0011-ai-vendor-strategy.md`
What are we working on now	`03_PROGRESS.md`
What did we ship last	`../CHANGELOG.md`
What’s the story behind some feature	`04_JOURNAL.md` — chronological narrative
What might we explore next	`discussions/` — exploratory, dated, may or may not become real

Discussing → coming to a decision

The pattern that’s working for ARCIVE so far:

Problem surfaces — in a code review, a planning chat, a “wait, why are we…?” moment.
Working notes in discussions/ — date-stamped markdown file, exploratory, captures options + tradeoffs + what credible reference points are doing. Doesn’t commit ARCIVE to anything. Examples: 2026-05-04_multimodal_expansion.md, 2026-05-05_ai_strategy_architecture.md.
Discuss with cofounder / team / Claude / ChatGPT — paste the discussion doc into chat, work through it, push back, refine.
Decide — when the choice is clear and durable, write an ADR in decisions/ capturing the decision, options considered, and consequences. Cross-link from the discussion doc.
Implement — code references the ADR by number in commit messages and code comments where relevant.

The discussion docs are cheap and frequent; the ADRs are immutable and rare. Don’t skip the discussion step — if a decision feels obvious enough to skip, it usually means the alternatives weren’t actually considered.

Source-of-truth split

Three surfaces, one source. All kept in lockstep:

Repo /docs/ (this folder) — engineering source of truth. Edit here, commit, push. Everything else follows.
docs.arcive.io — partner-friendly rendered view, auto-rebuilt on every push to master. Astro Starlight; config lives at apps/docs/astro.config.mjs.
Notion mirror — partner-collaboration surface. Discussions get partner sign-off in Notion before being promoted to ADRs in the repo. Synced via the /sync-notion slash command.

The two mirrors are write-rare: only /sync-notion and the docs site’s auto-rebuild touch them. Don’t create a fourth copy by hand.

What NOT to do

Don’t create a fourth doc surface. The two mirrors above are sanctioned and auto-synced; a hand-maintained Confluence / Linear Docs / Google Doc copy will drift within weeks.
Don’t edit ADRs after they’re accepted. Status Accepted means immutable. If a decision changes, write a new ADR that links back and supersedes it.
Don’t promote a discussion note to an ADR by editing in place. The discussion is the trail; the ADR is the conclusion. Keep both.
Don’t share apps/web/.env.local or apps/mobile/.env.local in chat for any reason. Use the share-helpers above only against files in docs/ and other safe paths.