Coop

A browser-first, local-first extension and companion receiver PWA for turning scattered knowledge into reviewed, shared coop memory.

Coop helps groups capture what would otherwise get lost -- open tabs, voice memos, photos, files, and links -- then review, refine, and publish what matters. The extension is the main product surface. The companion PWA handles mobile and secondary-device capture. Core capture, review, local AI refinement, and private intake stay in the browser. The repo also includes a small signaling/API layer for peer discovery and optional Yjs document sync.

A coop is Coop's shared group workspace and memory layer: the place where reviewed drafts, published artifacts, board views, and proof material become visible to members.

Today, Coop is strongest as a mock-first staged-launch product: browser capture and review are implemented, receiver pairing and private intake sync are implemented, local AI refinement is implemented, and shared coop publishing is implemented. Live Safe, live archive delegation, and live session-capability rails exist as separate second-gate or operator flows rather than the default public posture.

Current Status

As of March 28, 2026:

• the automated mock-first staged-launch bar is green
• Coop is documentable and demoable in its current mock-first posture
• the remaining public-release blocker is manual real-Chrome confirmation of popup Capture Tab and Screenshot success paths
• live Safe, archive, and session-capability rails remain a separate second gate

Current release references:

• Current Release Status
• Testing & Validation
• Demo & Deploy Runbook
• Live Rails Operator Runbook

How It Works

1. Capture -- Round up browser tabs with a shortcut in the extension. Record audio, snap photos, attach files, or share links from your phone through the companion receiver PWA.
2. Refine -- A local in-browser agent and inference cascade help turn captures into candidates, drafts, and next steps. Refinement runs locally in the browser through WebGPU/WASM/heuristic tiers rather than a hosted inference backend.
3. Review -- Members review candidates and drafts in the popup and Chickens before anything becomes shared coop state.
4. Share -- Publish reviewed drafts into a coop -- the group's shared workspace and memory layer -- sync them through Coop's local-first Yjs layer, open board and proof views, and export archive or proof material. Onchain, live archive, and operator execution flows remain mode-gated rather than default public behavior.

Main Surfaces

In the current product:

• Popup handles quick capture, quick review, create/join flows, and feed access
• Chickens handles the working queue for candidates, drafts, and publish prep
• Coops handles shared coop state, board/proof access, and archive-related actions
• Roost is the Green Goods member workspace in the current UI
• Nest handles members, receiver pairing, operator controls, and settings
• Receiver is the mobile and secondary-device capture surface

The older product story still uses "Roost" as the metaphor for human judgment. In the live UI, general review work now lives primarily in Popup and Chickens, while Roost is reserved for Green Goods member actions.

Use Cases

• Community coordination groups -- Bioregional networks, regen communities, and contributor circles can pool knowledge across members without centralizing raw context on a single platform.
• Research and grant teams -- Capture evidence across many sources, refine it locally, and turn the strongest leads into reviewed drafts and coop memory.
• Capital formation and evidence packaging -- Assemble attestations, work logs, and shared research into coherent proposals, with stronger onchain and archive rails available when those modes are intentionally enabled.
• Families and friends -- Use Coop as a shared memory capsule for trips, gardens, history, or any group project where everyone contributes fragments.
• Personal knowledge management -- Use Coop solo as a browser-first, local-first capture and review tool with optional sync, archive, and export paths.

Key Features

Implemented Today

• Capture and intake -- Browser tabs in the extension, plus audio, photos, files, and links in the receiver PWA. Cross-device receiver pairing lets mobile captures land in the extension's private intake before review.
• Review and publish -- Popup and Chickens workflows for candidate review, draft editing, categorization, and publish decisions.
• Local AI refinement -- A 16-skill agent pipeline with a three-tier local inference cascade (WebGPU, WASM, heuristics). The system is designed to work without hosted inference or API keys.
• Local-first sync -- Yjs CRDT sync with y-webrtc peers, y-websocket document sync support, and outbox tracking for publish-related events.
• Board, proof, and export paths -- Coop board views, archive receipts, and snapshot/artifact/ receipt export flows are surfaced today.
• Passkey-first identity -- WebAuthn-based identity with no wallet-extension-first requirement.

Available With Mode Or Gate Qualifiers

• Onchain rails -- Safe/ERC-4337 flows, anchor actions, and other live onchain behavior are mock-first by default and move behind a separate live gate when intentionally enabled.
• Archive live rails -- Storacha/Filecoin-backed archive delegation exists, but live archive credentials and trusted-node behavior are operator-only paths rather than the default public release posture.
• Anonymity features -- Coop's baseline privacy posture is local-first capture and explicit publish. Privacy mode surfaces anonymous-publish UI and stealth-address UI. The current anonymous publish path hides the author label in published artifacts; proof-backed ZK membership attachment remains an integration path rather than something this README should treat as fully shipped default behavior.
• Green Goods workflows -- Member work submission, operator approvals and assessments, GAP reconciliation, and Hypercert/Karma GAP packaging exist in the product model, with live behavior depending on mode, authority, and environment.
• ERC-8004 / FVM registry -- Agent identity and registry flows exist in the repo and runtime model, but should be read as gated infrastructure capabilities rather than baseline public-launch behavior.

Anonymity, Archiving, and Portability Notes

• Local-first by default -- Raw captures stay local until a person explicitly shares or syncs them.
• Anonymity is not the default -- Anonymous publish is a user-enabled path, distinct from the baseline local-only capture model.
• Export is the primary surfaced portability path today -- Snapshot/artifact/receipt export is wired into the current UI. Restore/import primitives also exist in shared modules and tests, but they are not yet presented as the primary polished end-user recovery flow.

Architecture

Bun monorepo with four runtime packages, plus a docs workspace and a contracts sidecar:

Package	Description
@coop/shared	Schemas, flows, sync contracts, and shared modules: agent, app, archive, auth, blob, coop, erc8004, fvm, greengoods, member-account, onchain, operator, permit, policy, privacy, receiver, session, stealth, storage, transcribe
@coop/app	Landing page + receiver PWA shell (audio, photo, file, link capture)
@coop/extension	MV3 browser extension -- popup (screen router, share menu), sidepanel (tab router, coop selector, filter popover), background handlers, offscreen workers
@coop/api	Hono + Bun TypeScript signaling relay with optional Yjs document sync persistence, deployed on Fly.io

Supporting directories outside the runtime four-pack:

• docs/ -- Docusaurus workspace for docs.coop.town
• packages/contracts/ -- Foundry sidecar for Solidity contracts and deployment artifacts

Build order: shared -> app -> extension (shared is the dependency root for the runtime packages).

Key Principles

• Browser-First -- The extension is the primary product surface; core capture and local analysis do not depend on hosted inference.
• Local-First -- All data stays on your device until you explicitly share. Dexie for structured data, Yjs for CRDT sync.
• Passkey-First -- No wallet extensions required. WebAuthn passkey identity bridged to onchain Safe accounts.
• Offline Capable -- Works without internet, syncs when connected.
• Explicit Sharing -- Review and publish remain human decisions. Anonymous publish is a separate user-enabled option, not the default path.

Standards

ERC-4337 (account abstraction), ERC-1271 (signature validation), EIP-712 (typed structured data), ERC-7579 (modular smart accounts), ERC-5564 (stealth addresses), ERC-8004 (onchain agent registry), Semaphore (ZK group membership), Storacha/Filecoin (permanent archiving), Yjs CRDTs (conflict-free sync).

Local Development

Coop pins Node 22 in .mise.toml. Bun is the workspace package manager, but the docs site still depends on a working Node toolchain.

Recommended shell bootstrap:

mise install
eval "$(mise activate zsh)"
node -v

node -v should report v22.x before you run the docs commands. If your shell still resolves an older Node first, fix that before running bun run docs:dev or bun run docs:build.

bun install              # Install dependencies
bun dev                  # Start app + extension concurrently
bun dev:app              # Start app only
bun dev:extension        # Start extension only (WXT dev + Chromium)
bun dev:api              # Start API server
bun run test             # Run unit tests (vitest)
bun run test:e2e         # Run Playwright E2E tests
bun run test:visual      # Run visual regression tests
bun run build            # Build everything (shared -> app -> extension)
bun format && bun lint   # Format (Biome) and lint workspace
bun run validate smoke   # Fast confidence pass
bun run validate:store-readiness
bun run validate:production-readiness
bun run validate:production-live-readiness
bun run validate list    # List all available validation suites

Note: Always use bun run test (not bun test). The former runs vitest with proper environment configuration; the latter uses Bun's built-in runner and ignores vitest config.

Environment

Single .env.local at the repository root (never create package-specific .env files).

Variable	Description	Default
VITE_COOP_CHAIN	Target chain: sepolia or arbitrum	sepolia
VITE_COOP_ONCHAIN_MODE	On-chain mode: mock or live	mock
VITE_COOP_ARCHIVE_MODE	Archive mode: mock or live	mock
VITE_COOP_SESSION_MODE	Session mode: off, mock, or live	off
VITE_COOP_PRIVACY_MODE	Toggle privacy-mode surfaces such as anonymous publish UI and stealth-address UI (on or off)	off
VITE_COOP_SIGNALING_URLS	Comma-separated WebSocket signaling endpoints	wss://api.coop.town
VITE_COOP_RECEIVER_APP_URL	Receiver PWA base URL	http://127.0.0.1:3001
VITE_PIMLICO_API_KEY	For live Safe/ERC-4337 operations	--

For Playwright E2E runs, the repo starts its own local signaling server automatically.

Release Posture

Coop's current release posture is mock-first.

• Automated mock-first release bar: bun run test, bun run test:coverage, bun run build, bun run validate:store-readiness, and bun run validate:production-readiness
• Remaining public-release blocker: manual Chrome popup QA for real-click Capture Tab and Screenshot
• Live Safe, archive, and session-key rails remain a second gate behind bun run validate:production-live-readiness

For public Chrome Web Store candidates, keep VITE_COOP_ONCHAIN_MODE, VITE_COOP_ARCHIVE_MODE, and VITE_COOP_SESSION_MODE on the mock-first path unless the live-rails gate is intentionally being exercised.

Canonical references:

• Current Release Status
• Testing & Validation
• Demo & Deploy Runbook
• Live Rails Operator Runbook

Documentation

Current-state docs:

• Action Domain Map
• Current Release Status
• Demo & Deploy Runbook
• Testing & Validation
• Receiver Pairing & Intake
• Builder Getting Started
• Architecture
• Extension
• App
• Environment Reference
• Live Rails Operator Runbook
• Extension Install & Distribution
• Chrome Web Store Checklist
• Chrome Web Store Reviewer Notes
• Agent Harness
• Agent Registry & API Server

Deep reference and architecture:

• Original Introduction
• Product Requirements
• Coop OS Architecture vNext
• Knowledge Sharing & Scaling
• Green Goods Integration
• Privacy & Stealth Addresses
• Policy, Sessions & Permits
• Scoped Roadmap
• EF Mandate Alignment
• Design Direction
• Audio & Asset Ops

Project Foundation

Coop is the browser-native coordination membrane built on ideas forming across the wider community coordination work:

• Local-first collaboration over server-centric products
• Explicit shared memory instead of fragmented chat history
• Durable long-memory archives that communities can keep, fork, and migrate
• Impact, governance, and capital formation as connected workflows
• Green Goods as the onchain substrate for gardens, attestations, and collective capital flows

The goal is to make it easier for communities to move from context to coordination, from coordination to evidence, and from evidence to capital. Each coop becomes a living knowledge garden with a shared local-first memory membrane, stronger local analysis, long-memory publishing into Filecoin, Green Goods garden bindings, and smart-account-mediated execution for proposals, attestations, and treasury flows when those rails are intentionally enabled.

Brand

Coop uses chicken metaphors throughout. Open browser tabs are Loose Chickens. The human review step is still called the Roost in the product story, even though the current sidepanel Roost tab is the Green Goods member workspace. The shared feed is the Coop Feed. Creating a new shared space is Launching the Coop. The success chime is the Rooster Call.