Merge pull request #555 from spacedriveapp/spaceui

SpaceUI migration

Author: jamiepine

.agents/skills/commit-all/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: commit-all
+description: Use this skill when the user asks to "commit all", "commit everything", or wants all outstanding changes committed. Groups unrelated changes into separate, well-described commits instead of one catch-all commit.
+---
+
+# Commit All
+
+## Goal
+
+Commit every outstanding change in the working tree — but group unrelated changes into separate, informative commits so the git history stays useful.
+
+## Workflow
+
+1. **Survey all changes.** Run `git status` and `git diff` (staged + unstaged) to see the full picture. Include untracked files.
+2. **Identify logical groups.** Cluster files by the change they belong to. A "group" is a set of files that were modified for the same reason (e.g. a bug fix, a new feature, a config tweak, a dependency update). Use file paths, diff content, and your understanding of the codebase to decide.
+3. **Order commits.** Infra/config/dependency changes first, then library/core changes, then feature/UI changes, then docs/polish.
+4. **For each group, create one commit:**
+   - Stage only the files belonging to that group (`git add <file> ...`). Never use `git add -A` or `git add .`.
+   - Write a concise, informative commit message that describes *what* changed and *why*. Follow the repo's existing commit style (check `git log --oneline -10`).
+   - Do not lump unrelated changes together just because they're small.
+5. **Verify.** After all commits, run `git status` to confirm the tree is clean. Run `git log --oneline -n <N>` (where N = number of commits created) to show the user what was committed.
+
+## Commit Message Rules
+
+- Keep the subject line under 72 characters.
+- Use imperative mood ("add", "fix", "update", not "added", "fixes").
+- If a change is trivial (whitespace, typo, formatting), it's fine to batch those into one commit labeled accordingly.
+- End every commit message with the Co-Authored-By trailer.
+
+## Hard Rules
+
+- Never combine unrelated changes in one commit.
+- Never skip or discard changes — everything gets committed.
+- Never use `git add -A` or `git add .`.
+- Do not push. Only commit locally.
+- Do not commit files that look like they contain secrets (`.env`, credentials, tokens). Warn the user about those instead.

.agents/skills/writing-guide/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: writing-guide
+description: Use when writing or editing any Spacebot copy — README sections, docs, release notes, marketing text, design doc summaries. Covers voice, tone, patterns to avoid, and what good Spacebot writing sounds like.
+---
+
+# Writing Guide
+
+Spacebot copy should sound like a confident engineer wrote it, not a language model. The test: would a developer reading the README think "someone knows what they're talking about" or "this was AI-generated"? These rules exist because the second outcome is common and costs credibility.
+
+## Voice
+
+Direct. Technical. No hedging. Short sentences with real content. Lead with the fact, not the framing. State what something is — not what it isn't.
+
+The tagline sets the tone: "The agent harness that runs teams, communities, and companies." That's a claim. It doesn't explain itself. Good Spacebot copy makes claims and lets the detail below earn them.
+
+## Patterns to Avoid
+
+These are the specific patterns that make copy sound AI-generated. Avoid all of them.
+
+**Em dashes in prose sentences.** Em dashes are fine in bullet point labels ("**Shell** — run arbitrary commands") but not inside sentences. Replace with a comma, a period, or restructure.
+
+Bad: "The cortex sees across all channels — the only process with full system scope."
+Good: "The cortex is the only process that sees across all channels."
+
+**"Not X. Not Y." openers.** Starting a description by saying what something isn't.
+
+Bad: "Not markdown files. Not unstructured vectors. Spacebot's memory is..."
+Good: "Spacebot's memory is a typed, graph-connected knowledge system."
+
+**"This isn't X, it's Y."** Classic AI construction. Just say the thing.
+
+Bad: "This isn't a generic claim — it's four specific mechanisms."
+Good: "Spacebot builds on itself through four specific mechanisms."
+
+**"The result is..." and "The through-line:"** Setup language that delays the actual point.
+
+Bad: "The result is an agent that works out of the box."
+Good: "It works out of the box."
+
+**"No X. No Y." closers.** Ending a paragraph with a string of negatives.
+
+Bad: "No heartbeat.json. No drift."
+Good: Just cut it, or fold it into the sentence that precedes it.
+
+**"This is the most important X."** Let the reader decide what's important.
+
+Bad: "This is the most important structural difference between Spacebot and every other agent harness."
+Good: Just state the difference.
+
+**Semicolons in prose.** Use a period.
+
+Bad: "The agent proposes; you decide."
+Good: "The agent proposes. You decide."
+
+**Parallel triplets.** Three consecutive "same X, same Y, same Z" constructions sound mechanical.
+
+Bad: "Same context, same memories, same understanding."
+Good: "They have the full conversation history."
+
+**"Not only X, but also Y."** Pick one.
+
+**Generic improvement claims.** Never say "self-improving" or "gets smarter." Name the actual mechanism.
+
+Bad: "Spacebot learns from experience."
+Good: "After a conversation goes idle, a background branch reviews the history and saves skills and memories worth keeping."
+
+## What Spacebot Is Opinionated About
+
+When describing Spacebot's opinions, name them specifically: the process model, memory schema, and task lifecycle. Don't say its opinions are about "one thing" — they cover multiple things. The unifying idea is that state belongs in structured storage, not markdown files the LLM manages.
+
+## What Is and Isn't a Differentiator
+
+**Is a differentiator:**
+- The task system as the structural foundation of autonomy
+- True process-level concurrency across users
+- Typed memory graph in SQLite with graph edges and hybrid search
+- Autonomy channel with full context on wake, state tracked through tasks not files
+- Spacedrive integration for cross-device execution and safe data access
+
+**Is not a differentiator:**
+- Skills (every harness has skills, the format is not special)
+- "Self-improving" as a generic claim
+- Internal implementation details the user doesn't see
+
+Don't advertise internal improvements as external features. If Spacebot previously sent cold context to workers and now sends full context, that's an internal fix. The user-visible claim is "the autonomy channel wakes with full context" — not "unlike the old approach."
+
+## The Spacedrive Story
+
+Two layers:
+
+**What exists today:** multi-device access via P2P, remote execution via Spacedrive's permission system, file system intelligence via context nodes, safe data access via Prompt Guard 2 screening.
+
+**Where it's going:** team + personal library switching, org graph delegation, full company deployment model.
+
+Be honest about which is which. Don't present the vision as current capability.
+
+## Prose Structure
+
+Opening paragraphs should be 3-4 sentences. Lead with the strongest claim. No setup sentences ("In this section, we'll cover..."). No closing sentences that summarize what was just said.
+
+Bullet points are for lists of discrete items. Prose is for explanation, argument, and narrative. Don't bullet-point things that belong in prose.
+
+Section headers are short nouns or short sentences. No gerunds ("Building the Memory System"). No questions ("What Is the Task System?").
+
+## Words to Avoid
+
+comprehensive, utilize, harness (as a verb), unlock, revolutionary, groundbreaking, remarkable, pivotal, powerful, exciting, cutting-edge, seamless, robust, leverage, paradigm, ecosystem (when not literally true), journey, dive deep, explore, embark.
+
+Also avoid: "at its core," "under the hood," "out of the box" (unless used once, intentionally), "world-class," "best-in-class."

.gitignore

@@ -2,6 +2,9 @@
 .DS_Store
 .fastembed_cache
 .build/
+*.db
+*.db-shm
+*.db-wal
 
 # Interface
 interface/node_modules/

CONTRIBUTING.md

@@ -0,0 +1,187 @@
+# Contributing
+
+Contributions welcome. Read [RUST_STYLE_GUIDE.md](RUST_STYLE_GUIDE.md) before writing any code, and [AGENTS.md](AGENTS.md) for the full implementation guide.
+
+---
+
+## Prerequisites
+
+- **Rust** 1.85+ with `rustfmt` and `clippy`
+- **protoc** (protobuf compiler)
+- **bun** (for frontend/interface work)
+- **just** (`brew install just` or `cargo install just --locked`)
+
+Optional: [Nix flakes](https://nixos.org/) for isolated dev environments (`nix develop` gives you everything).
+
+---
+
+## Getting Started
+
+1. Fork the repo and create a feature branch
+2. Run `./scripts/install-git-hooks.sh` (installs a pre-commit hook that runs `cargo fmt`)
+3. `cargo build` to verify the backend compiles
+4. For frontend work: `cd interface && bun install`
+5. Make your changes
+6. Run `just preflight && just gate-pr`
+7. Submit a PR
+
+---
+
+## PR Gate
+
+Every PR must pass `just gate-pr` before merge. This mirrors CI and checks:
+
+1. **Migration safety** — new migrations only, never edit existing ones
+2. **Formatting** — `cargo fmt --all -- --check`
+3. **Compile** — `cargo check --all-targets`
+4. **Lints** — `cargo clippy --all-targets -Dwarnings`
+5. **Tests** — `cargo test --lib`
+6. **Integration compile** — `cargo test --tests --no-run`
+
+Use `just gate-pr --fast` to skip clippy and integration compile during iteration.
+
+The frontend CI (`interface-ci.yml`) runs `bun ci` and `bunx tsc --noEmit` on interface changes.
+
+---
+
+## Project Structure
+
+Single binary crate (no workspace). Key directories:
+
+```
+src/
+├── main.rs           — CLI entry, config, startup
+├── lib.rs            — re-exports
+├── config.rs         — config loading/validation
+├── error.rs          — top-level Error enum
+├── llm/              — LlmManager, model routing, providers
+├── agent/            — Channel, Branch, Worker, Compactor, Cortex
+├── hooks/            — SpacebotHook, CortexHook
+├── tools/            — reply, branch, spawn_worker, memory_*, etc.
+├── memory/           — MemoryStore, hybrid search, graph ops
+├── messaging/        — Discord, Telegram, Slack, webhook adapters
+├── conversation/     — history persistence, context assembly
+├── cron/             — scheduler, CRUD
+├── identity/         — SOUL.md, IDENTITY.md, USER.md loading
+├── secrets/          — encrypted credentials (AES-256-GCM)
+├── settings/         — key-value settings
+└── db/               — SQLite migrations, connection setup
+
+interface/            — Dashboard UI (Vite + React + TypeScript)
+prompts/              — LLM prompts as markdown (not Rust strings)
+docs/                 — Documentation site (MDX)
+desktop/              — Tauri desktop app
+scripts/              — Dev tooling (hooks, gates, builds)
+```
+
+Module roots use `src/module.rs`, **not** `src/module/mod.rs`.
+
+---
+
+## Rust Conventions
+
+The full guide is in [RUST_STYLE_GUIDE.md](RUST_STYLE_GUIDE.md). Key points:
+
+**Imports** — three tiers separated by blank lines: (1) crate-local, (2) external crates, (3) std.
+
+**Error handling** — domain errors per module, wrapped by top-level `Error` enum via `#[from]`. Use `?` and `.context()`. Never silently discard with `let _ =`.
+
+**Async** — native RPITIT for async traits (not `#[async_trait]`). `tokio::spawn` for concurrent work. Clone before moving into async blocks.
+
+**Logging** — `tracing` crate, never `println!`. Structured key-value fields. `#[tracing::instrument]` for spans.
+
+**Lints** (enforced in Cargo.toml): `dbg_macro = "forbid"`, `todo = "forbid"`, `unimplemented = "forbid"`.
+
+**Testing** — `#[cfg(test)]` at end of file. `#[tokio::test]` for async. `.unwrap()` is fine in tests only.
+
+---
+
+## Frontend (Interface)
+
+Use **bun** exclusively — never npm, pnpm, or yarn.
+
+```bash
+cd interface
+bun install       # install deps
+bun run dev       # dev server
+bun run build     # production build
+```
+
+### SpaceUI Packages
+
+The dashboard uses `@spacedrive/*` packages published to npm from the [spaceui](https://github.com/spacedriveapp/spaceui) monorepo:
+
+- `@spacedrive/primitives` — base UI components
+- `@spacedrive/ai` — AI chat components
+- `@spacedrive/forms` — form components
+- `@spacedrive/explorer` — file explorer components
+- `@spacedrive/tokens` — design tokens
+
+`package.json` points to npm versions (e.g. `"^0.2.0"`). CI pulls from the registry. For local development, `bun link` overrides them with your local copies.
+
+**Local SpaceUI development:**
+
+Clone the spaceui repo adjacent to this one, then run the link command:
+
+```bash
+git clone https://github.com/spacedriveapp/spaceui ../spaceui
+just spaceui-link
+```
+
+This builds SpaceUI, registers all packages as global links, and connects them to `interface/`. Use `bun run watch` in the SpaceUI repo for automatic rebuilds.
+
+To unlink and restore npm versions: `just spaceui-unlink`.
+
+---
+
+## Useful Commands
+
+```bash
+just preflight                # validate git/remote state
+just gate-pr                  # full PR gate (mirrors CI)
+just gate-pr --fast           # skip clippy + integration compile
+just typegen                  # generate TypeScript API types
+just check-typegen            # verify types match
+just build-opencode-embed     # build OpenCode embed bundle
+just bundle-sidecar           # build Tauri sidecar
+just desktop-dev              # run desktop app in dev mode
+just update-frontend-hash     # update Nix hash after frontend dep changes
+```
+
+---
+
+## Migrations
+
+SQLite migrations are **immutable**. Never edit an existing migration file. Always create a new timestamped migration for schema changes.
+
+---
+
+## Architecture
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design. The short version: five process types, each with one job.
+
+- **Channels** — user-facing LLM, stays responsive, never blocks on work
+- **Branches** — fork channel context to think, return conclusion, get deleted
+- **Workers** — independent task execution with focused tools, no conversation context
+- **Compactor** — programmatic context monitor, triggers compaction before channels fill up
+- **Cortex** — system observer, generates memory bulletins, supervises processes
+
+Key rule: **never block the channel**. Branch to think, spawn workers to act.
+
+---
+
+## Release Process
+
+Releases are triggered by git tags (`v*`). The CI workflow:
+
+1. Verifies `Cargo.toml` version matches the tag
+2. Builds multi-platform binaries (x86_64/aarch64, Linux/macOS)
+3. Builds Docker images (amd64/arm64)
+4. Creates a GitHub release with binaries
+5. Updates the Homebrew tap
+
+---
+
+## License
+
+FSL-1.1-ALv2 ([Functional Source License](https://fsl.software/)), converting to Apache 2.0 after two years.