docs: add README with badges, architecture, and quickstart

1+# Cospan
2+
3+[![CI](https://github.com/cospan-dev/cospan/actions/workflows/ci.yml/badge.svg)](https://github.com/cospan-dev/cospan/actions/workflows/ci.yml)
4+[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
5+
6+**Decentralized code collaboration with structural version control.**
7+
8+Cospan replaces git's text-based VCS with [panproto](https://github.com/panproto/panproto)-vcs, a mathematically-founded version control system where merges are categorical pushouts, diffs are structural, and every object is typed by a Generalized Algebraic Theory. Built on [ATProto](https://atproto.com/) for federated identity and data portability.
9+
10+## What makes Cospan different
11+
12+- **Structural diffs, not line diffs.** When two developers modify the same struct, Cospan sees structural schema modifications and computes provably commutative merges instead of textual three-way merge conflicts.
13+- **248 language support.** Full-AST parsing via [panproto-grammars](https://github.com/panproto/panproto) turns source files into typed schema graphs. Every function, class, statement, and expression is a vertex in the graph.
14+- **Cross-protocol schema tracking.** A Protobuf schema change can show which ATProto Lexicons and SQL tables downstream are affected, with auto-generated migration lenses for each hop.
15+- **Federated on ATProto.** Your identity is a DID. Your repos, issues, stars, and follows live in your PDS. Self-host a node on a Raspberry Pi or use the public AppView.
16+- **Tangled interop.** Subscribes to `sh.tangled.*` records and translates them via panproto lenses, so Tangled repos appear alongside native Cospan repos.
17+
18+## Architecture
19+
20+```
21+┌─────────────────────────────────────────────────────┐
22+│                    Frontend                          │
23+│              SvelteKit 2 + Svelte 5                  │
24+│     31 routes, dark oklch theme, ATProto OAuth       │
25+└──────────────────────┬──────────────────────────────┘
26+                       │ XRPC
27+┌──────────────────────┴──────────────────────────────┐
28+│                    AppView                           │
29+│           Rust + Axum + PostgreSQL                   │
30+│  36 XRPC endpoints, Jetstream indexer, SSE, OAuth    │
31+└──────────────────────┬──────────────────────────────┘
32+                       │ XRPC
33+┌──────────────────────┴──────────────────────────────┐
34+│                     Node                             │
35+│            Rust + panproto-vcs FsStore               │
36+│  8 XRPC handlers, git smart HTTP, validation        │
37+└─────────────────────────────────────────────────────┘
38+```
39+
40+**Source of truth:** 20 ATProto Lexicon schemas in `packages/lexicons/dev/cospan/`
41+
42+**Codegen pipeline:** Lexicons → panproto `parse_lexicon()` → schema morphisms → SQL DDL + Rust types + TypeScript interfaces
43+
44+## Getting started
45+
46+### Prerequisites
47+
48+- Rust 1.85+ (`rustup update stable`)
49+- Node.js 22+ and pnpm 9+
50+- PostgreSQL 17
51+- Docker (optional, for database)
52+
53+### Quick start
54+
55+```bash
56+# Clone
57+git clone https://github.com/cospan-dev/cospan.git
58+cd cospan
59+
60+# Start PostgreSQL
61+docker compose up db redis -d
62+
63+# Copy env
64+cp .env.example .env
65+
66+# Build and run
67+cargo run -p cospan-node &    # Node on :3001
68+cargo run -p cospan-appview & # AppView on :3000
69+
70+# Frontend
71+cd apps/web
72+pnpm install
73+pnpm build
74+PORT=3000 node build/index.js
75+```
76+
77+### Using the CLI
78+
79+Cospan repos are managed through panproto's `schema` CLI:
80+
81+```bash
82+# Initialize a repo
83+schema init
84+
85+# Add and commit
86+schema add .
87+schema commit -m "initial commit"
88+
89+# Push to a cospan node
90+schema remote add origin cospan://node.cospan.dev/did:plc:xyz/my-project
91+schema push origin main
92+
93+# Or use git transparently
94+git push cospan://node.cospan.dev/did:plc:xyz/my-project main
95+```
96+
97+## Lexicon schemas
98+
99+All 19 record types under `dev.cospan.*`:
100+
101+| Record | Description |
102+|--------|-------------|
103+| `dev.cospan.node` | Node declaration |
104+| `dev.cospan.actor.profile` | User profile (links to Bluesky) |
105+| `dev.cospan.repo` | Repository with protocol type |
106+| `dev.cospan.vcs.refUpdate` | Ref update with algebraic metadata |
107+| `dev.cospan.repo.issue` | Issue with schema element references |
108+| `dev.cospan.repo.issue.comment` | Issue comment |
109+| `dev.cospan.repo.issue.state` | Issue state transitions |
110+| `dev.cospan.repo.pull` | Merge request with pushout preview |
111+| `dev.cospan.repo.pull.comment` | MR comment with review decisions |
112+| `dev.cospan.repo.pull.state` | MR state transitions |
113+| `dev.cospan.repo.dependency` | Cross-repo dependency via theory morphism |
114+| `dev.cospan.repo.collaborator` | Repo RBAC |
115+| `dev.cospan.feed.star` | Star |
116+| `dev.cospan.feed.reaction` | Reaction |
117+| `dev.cospan.graph.follow` | Follow |
118+| `dev.cospan.label.definition` | Label |
119+| `dev.cospan.org` | Organization |
120+| `dev.cospan.org.member` | Org membership |
121+| `dev.cospan.pipeline` | CI pipeline with algebraic checks |
122+
123+## Project structure
124+
125+```
126+cospan/
127+├── crates/
128+│   ├── cospan-node/        # panproto-vcs node server (Axum)
129+│   ├── cospan-appview/     # ATProto AppView (Axum + PostgreSQL)
130+│   └── cospan-codegen/     # Lexicon → SQL/Rust/TS codegen
131+├── apps/
132+│   └── web/                # SvelteKit frontend
133+├── packages/
134+│   ├── lexicons/           # dev.cospan.* Lexicon JSON schemas
135+│   └── types/              # Generated TypeScript types
136+├── docker-compose.yml
137+├── Caddyfile               # Production reverse proxy
138+└── Cargo.toml              # Rust workspace
139+```
140+
141+## panproto integration
142+
143+Cospan is a thin collaboration layer on top of panproto. It uses:
144+
145+| Crate | Purpose |
146+|-------|---------|
147+| `panproto-vcs` | Content-addressed schema VCS (FsStore, commits, merges) |
148+| `panproto-parse` | Full-AST parsing for 248 languages via tree-sitter |
149+| `panproto-project` | Multi-file project assembly via schema coproduct |
150+| `panproto-git` | Bidirectional git ↔ panproto-vcs bridge |
151+| `panproto-check` | Breaking change detection and classification |
152+| `panproto-lens` | Auto-generated bidirectional migration lenses |
153+| `panproto-xrpc` | XRPC client for node push/pull/clone |
154+| `panproto-protocols` | ATProto Lexicon parsing and 77+ protocol definitions |
155+| `panproto-expr` | Expression language for structural search queries |
156+| `panproto-io` | Instance-level parse/emit for all protocols |
157+
158+## Development
159+
160+```bash
161+# Lint
162+cargo clippy --workspace -- -D warnings
163+
164+# Format
165+cargo fmt --all
166+
167+# Test (node + codegen, no database needed)
168+cargo test -p cospan-node -p cospan-codegen
169+
170+# Test (appview, needs PostgreSQL)
171+cargo test -p cospan-appview
172+
173+# Run codegen
174+cargo run -p cospan-codegen
175+
176+# Frontend dev
177+cd apps/web && pnpm dev
178+```
179+
180+## License
181+
182+[AGPL-3.0-or-later](LICENSE)