@openparachute/agent 0.1.0

package/docs/BRANCH-FORK-MAINTENANCE.md

@@ -0,0 +1,81 @@
+# Branch & Fork Maintenance Guidelines
+
+## Structure
+
+**`qwibitai/nanoclaw`** (upstream) — core engine with skill definitions (`.claude/skills/`). No channel code on `main`.
+
+**Channel forks** (`nanoclaw-whatsapp`, `nanoclaw-telegram`, `nanoclaw-slack`, etc.) — each fork = upstream + one channel's code applied. Users clone upstream, then merge a fork into their clone to add a channel.
+
+**`skill/*` and `feat/*` branches on upstream** — add features unrelated to channels (e.g. `skill/compact`, `skill/apple-container`). Users merge these into their clone to add capabilities. Channel-specific skill branches that duplicate the forks (e.g. `skill/whatsapp`, `skill/telegram`) are legacy.
+
+## How users add capabilities
+
+```
+user clones upstream main
+  ├── merges nanoclaw-whatsapp fork  → adds WhatsApp
+  ├── merges skill/compact branch    → adds /compact command
+  └── merges skill/apple-container   → switches to Apple Container
+```
+
+## Merge directions
+
+```
+upstream main ──→ channel forks     (forward merge to keep forks caught up)
+upstream main ──→ skill branches    (forward merge to keep branches caught up)
+```
+
+Forks and skill branches carry applied code changes. Users merge them into their own clones/forks to add capabilities. They are never merged back into upstream `main`.
+
+## Forward merge procedure
+
+```bash
+# In your local nanoclaw checkout
+git checkout main && git pull
+
+# For a fork:
+git fetch nanoclaw-whatsapp
+git checkout -B whatsapp-merge nanoclaw-whatsapp/main
+git merge main
+# Resolve conflicts (see below)
+# Remove upstream-only workflows (re-added by every merge since main has them):
+git rm .github/workflows/bump-version.yml .github/workflows/update-tokens.yml 2>/dev/null
+git push nanoclaw-whatsapp HEAD:main
+git checkout main && git branch -D whatsapp-merge
+
+# For a skill branch:
+git checkout -B skill/compact origin/skill/compact
+git merge main
+# Resolve conflicts (see below)
+git push origin skill/compact
+git checkout main && git branch -D skill/compact
+```
+
+## Conflict resolution
+
+The same files conflict every time:
+
+| File | Resolution |
+|------|------------|
+| `package.json` | Take main's version + keep fork/branch-specific deps |
+| `pnpm-lock.yaml` | `git checkout main -- pnpm-lock.yaml && pnpm install` |
+| `.env.example` | Combine: main's entries + fork/branch-specific entries |
+| `repo-tokens/badge.svg` | Take main's version (auto-generated) |
+
+Source code changes (e.g. `src/types.ts`, `src/index.ts`) usually auto-merge cleanly, but can conflict if both sides modify the same lines. **Always build and test after every forward merge** — auto-merged code can be silently wrong (e.g. referencing a renamed function or using a removed parameter) even when git reports no conflicts.
+
+## When to merge forward
+
+After any main change that touches shared files (`package.json`, `src/index.ts`, `CLAUDE.md`, etc.). Small frequent merges = trivial conflicts. Large infrequent merges = painful.
+
+## Fork setup
+
+When creating a new channel fork:
+
+1. Fork `nanoclaw` to `nanoclaw-{channel}`
+2. Remove upstream-only workflows: `bump-version.yml`, `update-tokens.yml`
+3. Add channel code, deps, env vars
+4. Forward-merge main immediately to establish a clean baseline
+
+## Dependencies
+
+Forks and branches add their own deps on top of upstream's. When upstream adds or removes a dependency, verify that forks/branches still build after the next forward merge — transitive dependency changes can break downstream code.

package/docs/README.md

@@ -0,0 +1,25 @@
+# parachute-agent Documentation
+
+Reference for engineers working on or integrating with parachute-agent (formerly paraclaw). Read [`architecture.md`](architecture.md) first — it covers the primitives, runtime model, schema, and trust zones in one place.
+
+## Map
+
+| Document | What's in it |
+|---|---|
+| [architecture.md](architecture.md) | Primitives, schema, runtime model, trust zones, integration with Parachute |
+| [architecture-diagram.md](architecture-diagram.md) | Visual breakdown of the host ↔ container split |
+| [parachute-integration.md](parachute-integration.md) | How parachute-agent plugs into the Parachute hub: install, OAuth, vault attachments |
+| [isolation-model.md](isolation-model.md) | The three-level isolation model (channel × messaging group × agent group × session) |
+| [SECURITY.md](SECURITY.md) | Threat model, AES-GCM secrets, master-key bootstrap, audit surface |
+| [api-details.md](api-details.md) | `/api/*` route catalogue with request/response shapes |
+| [agent-runner-details.md](agent-runner-details.md) | Container-side runtime: poll loop, MCP tools, provider abstraction |
+| [build-and-runtime.md](build-and-runtime.md) | Bun-on-host, Bun-in-container split — why two runtimes, how they communicate |
+| [db.md](db.md) | The three-database model (central + per-session inbound/outbound) |
+| [db-central.md](db-central.md) | Central DB schema reference (`~/.parachute/agent/agent.db`) |
+| [db-session.md](db-session.md) | Per-session DB schema reference (`inbound.db` + `outbound.db`) |
+| [docker-sandboxes.md](docker-sandboxes.md) | Optional micro-VM isolation via Docker Sandboxes |
+| [APPLE-CONTAINER-NETWORKING.md](APPLE-CONTAINER-NETWORKING.md) | macOS-native runtime via Apple Container |
+| [ollama.md](ollama.md) | Local open-weight model provider via Ollama |
+| [SDK_DEEP_DIVE.md](SDK_DEEP_DIVE.md) | Claude Agent SDK integration patterns |
+| [BRANCH-FORK-MAINTENANCE.md](BRANCH-FORK-MAINTENANCE.md) | Living-on-a-fork workflow (channels + providers branches) |
+| [cross-mount-stress/](cross-mount-stress/) | Empirical proof of the SQLite cross-mount invariants — why we don't collapse the per-session two-file split |