`-as-card, etc.). Never introduce or reintroduce a raw JSX element where a twui equivalent exists. Override twui defaults via `className` rather than reaching for the raw element.
- **Never create new CSS classes, CSS files, or inline `style={{...}}` hacks.** Style exclusively by composing existing component props/classNames, existing twui classNames (`twui-*`), semantic theme-token utilities (`bg-dark`, `bg-light`, `text-dark`, `text-primary`, `bg-primary`, `text-accent`, `bg-accent`, `text-secondary`, `border-slate-200`, etc.), and utility classes already used elsewhere in this codebase. Build up from what exists; extend component code only when the existing API cannot express the need.
- **Theming:** colors, radii, and fonts change only in `src/styles/main.css`: Cobble tokens as CSS vars on `:root` (light) and `.dark`, exposed in the `@theme inline` block as `paper`, `surface`, `sunken`, `ink`, `ink-secondary`, `ink-disabled`, `hairline`, `hairline-strong`, `on-ink`, `hue-
`, plus `shadow-popover` and `--m-fast/base/slow` motion vars (zeroed under reduced motion). Font is Lato (stand-in). Never hardcode hex colors, radii, or font stacks inside components. Hues are bot identity only, never state; use `src/dict/bot-hue-classes-dict.ts` for hue classes.
-- **Branding:** `public/logos/logo.svg` is the single source of truth for the logo mark; `logo-icon.tsx` renders it inline (via `BotStone`) and `logo.tsx` renders the stone beside the vector `Wordmark`. Whenever the logo changes, run `bun run gen:favicon` to regenerate `public/favicon.ico`, `public/favicon.png`, `public/apple-touch-icon.png`, and `public/logos/logo.png` (the last is used in emails). Font + favicon links live in `__root.tsx` `Head()`.
+- **Branding:** `docs/readme/hero-light.png`, `hero-dark.png`, `workspace-light.png` and `workspace-dark.png` are screenshots of the current app (chat and workspace dashboard, 1440px at 2x, downscaled to 1600px wide), committed and picked per theme by GitHub's `#gh-light-mode-only` / `#gh-dark-mode-only` fragment. They are not generated: when the UI changes, retake them from a seeded dev instance (`bun run seed`, `bun run seed:bots`) and keep the same names, so the README never shows an older dashboard. Never use `assets/handoff/assets/screens/*.png` for anything: that design is outdated. `public/logos/logo.svg` is the single source of truth for the logo mark; `logo-icon.tsx` renders it inline (via `BotStone`) and `logo.tsx` renders the stone beside the vector `Wordmark`. Whenever the logo changes, run `bun run gen:favicon` to regenerate `public/favicon.ico`, `public/favicon.png`, `public/apple-touch-icon.png`, and `public/logos/logo.png` (the last is used in emails). Font + favicon links live in `__root.tsx` `Head()`.
- **Site name:** brand literals live only in `src/data/site-data.ts`. Page meta titles, emails, and UI copy must interpolate `SiteData["SiteName"]` - never hardcode a brand name in page files.
## Conventions
diff --git a/README.md b/README.md
index 2442190..3842aaf 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,72 @@
-# Cobble
+
+
+
+
+
+A crew of small AI worker bots you host yourself.
+
+
+
[](https://github.com/Moduletrace/cobble/actions/workflows/ci.yml)
+[](LICENSE)
+[](https://cobble.moduletrace.org)
+[](https://bun.sh)
-A self-hosted crew of small AI worker bots.
+[Website](https://cobble.moduletrace.org) · [Install](#install) · [Features](#features) · [Development](#development) · [Architecture](AGENTS.md)
-Cobble gives you a coordinator bot and a crew of workers, each with its own
-job, models, memory and workspace. The crew talks to you in a chat, shares
-workspaces, runs routines on a schedule, and drives its own computers:
-Docker sandboxes with a browser, terminal, code editor and desktop that a
-bot can use and hand back to you when it needs help.
+
/ # each computer's home directory
+ bots// # each bot's files
+ workspaces// # files shared in a workspace
```
`.env` holds the port and the encryption keys. The keys encrypt sessions and
@@ -169,27 +251,38 @@ the app from a phone, run a proxy or tunnel in front of it (see
[HTTPS](#https)); the installed app, Web Push and voice need that secure
context.
-| Command | Purpose |
-| -------------------- | ------------------------------------ |
-| `bun run dev` | Development server |
-| `bun run start` | Production server on the host |
-| `bun run typecheck` | Type-check |
-| `bun run test` | Run the test suite |
-| `bun run seed` | Create the super admin from the CLI |
-| `bun run seed:bots` | Add a sample crew |
-| `bun run db:schema` | Sync the schema and types |
-| `bun run gen:favicon` | Regenerate favicons and PWA assets |
+| Command | Purpose |
+| --------------------- | ------------------------------------ |
+| `bun run dev` | Development server |
+| `bun run start` | Production server on the host |
+| `bun run typecheck` | Type-check |
+| `bun run test` | Run the test suite |
+| `bun run check:bundle`| Bundle budget after a build |
+| `bun run seed` | Create the super admin from the CLI |
+| `bun run seed:bots` | Add a sample crew |
+| `bun run db:schema` | Sync the schema and types |
+| `bun run gen:favicon` | Regenerate favicons and PWA assets |
-The app is Bun, [`@moduletrace/bunext`](https://github.com/Moduletrace/bunext),
-SQLite via [`@moduletrace/bun-sqlite`](https://github.com/Moduletrace/bun-sqlite),
-Tailwind CSS and the `@moduletrace/twui` component library. See
-[AGENTS.md](AGENTS.md) for the full architecture, routes, queue, harness and
-data model.
+Plain Node does not work: the app runs on Bun. The stack is Bun,
+[`@moduletrace/bunext`](https://github.com/Moduletrace/bunext) for
+filesystem routing, SQLite via
+[`@moduletrace/bun-sqlite`](https://github.com/Moduletrace/bun-sqlite),
+Tailwind CSS and the `@moduletrace/twui` component library. The model layer is
+one adapter over OpenAI-compatible APIs, so any compatible provider works.
-CI runs type-check and tests on every push and pull request. Releases are
-built by GitHub Actions and pushed to both registries. See
+See [AGENTS.md](AGENTS.md) for the full architecture, routes, queue, harness
+and data model. CI runs type-check and tests on every push and pull request;
+releases are built by GitHub Actions and pushed to both registries. See
[RELEASING.md](RELEASING.md) for the release and launch checklist.
+## Contributing
+
+Issues and pull requests are welcome, in English, on either
+[GitHub](https://github.com/Moduletrace/cobble) or
+[Gitea](https://git.tben.me/Moduletrace/cobble). Run `bun run typecheck` and
+`bun run test` before opening a pull request, and read
+[AGENTS.md](AGENTS.md) first: it documents the conventions the code follows.
+
## License
MIT. See [LICENSE](LICENSE).
diff --git a/docs/readme/hero-dark.png b/docs/readme/hero-dark.png
new file mode 100644
index 0000000..c57df03
Binary files /dev/null and b/docs/readme/hero-dark.png differ
diff --git a/docs/readme/hero-light.png b/docs/readme/hero-light.png
new file mode 100644
index 0000000..8cc54a2
Binary files /dev/null and b/docs/readme/hero-light.png differ
diff --git a/docs/readme/lockup-dark.svg b/docs/readme/lockup-dark.svg
new file mode 100644
index 0000000..6e8b03f
--- /dev/null
+++ b/docs/readme/lockup-dark.svg
@@ -0,0 +1 @@
+Cobble Cobble