Imported from Wqffles-com/botanical (
AGENTS.md). Install upstream withnpx skills add Wqffles-com/botanical. Copyright stays with the author.
Botanical
Always-on agent server: a Bun HTTP API, a web client, and swappable model providers. Postgres is optional. With DATABASE_URL unset, the API uses an in-memory store.
Codebase index
Start at docs/index/README.md. Product decisions are in docs/DECISIONS.md. Shipped and planned work is in docs/ROADMAP.md.
- docs/index/server.md — HTTP routes, turns, auth
- docs/index/agent-runtime.md — agent loop and permissions
- docs/index/providers.md — model and CLI adapters
- docs/index/tools.md — file, shell, and web tools
- docs/index/mcp.md — MCP client
- docs/index/db.md — schema and migrations
- docs/index/core.md — shared types and API client
- docs/index/web.md — web app routes and settings
- docs/index/ui.md — design tokens and shadcn primitives
- docs/index/e2e.md — browser tests
- docs/index/deploy-and-ci.md — images, compose, CI
Conventions
- Bun is the package manager and the API runtime (
package.json). TypeScript acrosspackages/. - Web UI is monochrome shadcn. Theme tokens and primitives live in
@botanical/ui(packages/ui/src/styles.css,packages/ui/src/components); add primitives with the shadcn CLI frompackages/ui(packages/ui/components.json). App screens stay inpackages/web. Color means something: status usesStatusBadgetones and the--success/--warning/--info/--destructivetokens, identity uses agent colors, and the user's accent only touches--primary. No raw palette classes (bg-amber-500) or hex in app code. - Postgres schema lives in
packages/db. SQL files underpackages/db/migrationsare ordered bypackages/db/migrations/meta/_journal.json(NNNN_tag.sqlmatches the journal tag).migrateDatabaseinpackages/db/src/migrate.tsapplies that journal, thenpackages/db/sql/guards.sql,packages/db/sql/bootstrap.sql, andpackages/db/sql/seed-agents.sql. Rootbun run db:migraterunspackages/db/src/cli.ts. The API also migrates on boot whenDATABASE_URLis set (packages/db/src/store.ts). - Only
packages/providerstalks to model vendors.
Commands
- Install:
bun install - Dev:
bun run dev(APIpackages/server, webpackages/webon port 3101) - Typecheck:
bun run typecheck - Build:
bun run build - Migrate:
bun run db:migrate - Index:
bun run check:index
Unit tests: bun test inside a package, or the package loop in .github/workflows/ci.yml (that loop skips packages/e2e). Root bun run test also runs the e2e package script, which probes a live web origin.
Do not run e2e against a live stack unless explicitly asked. bun run e2e:self-test uses the fixture in scripts/e2e/run.mjs.
Keep the index current (mandatory)
Any change that adds, moves, renames or deletes files, routes, tables, env vars, or packages must update the relevant file in docs/index/ in the same PR. Run bun run check:index before opening a PR. Reviewers should reject PRs that leave the index stale.
GitHub issues and PRs
Whenever you create an issue or pull request in GitHub, add Wqffles-com as assignee.
Whenever you create a pull request, unless told otherwise, watch it until CI is green: if it goes red, fix it and push; once it is green, merge it.
Every pull request body must reference the issue it fixes and declare it fixed with a closing keyword, e.g. Fixes #123.
Do not create routines (scheduled triggers, e.g. create_trigger or send_later) for pull requests. Watch PRs through PR activity subscriptions only.
Whenever you pick up a GitHub issue in a session, add the working on label to it.
Secrets
Do not commit secrets, .env files, or real API keys. Use .env.example for placeholders. See SECURITY.md.
