Repository Guide
Locate behavior in the owning app or package and run the correct development checks.
Workspace Map
| Location | Responsibility |
|---|---|
apps/backend | API, validation, persistence, orchestration, jobs, OpenAPI, integrations |
apps/frontend | Product routes, data loading, forms, Context, tasks, inbox, integrations |
apps/agents | Chat/worker runtime, harness adapter, workspace lifecycle, trusted MCP/CLI registries |
packages/types | Shared typed contracts and trusted integration runtime definitions |
packages/agent-packs | Git catalog, profile instructions, skills, validation, revision hashing |
packages/oblivectl | Authenticated agent control-plane CLI |
packages/organization-context | Local read-only contextctl verify |
packages/objectstore | Provider-neutral object storage and safe workspace operations |
packages/redis | Connection-injected cache, Pub/Sub, and Stream primitives |
packages/chat-commands | Shared chat command parsing/contracts |
sites/docs | Operator/developer knowledge base and generated API reference |
The root Bun workspace contains apps/* and packages/*. sites/ is a separate Bun workspace
with its own manifest, lockfile, isolated dependency layout, and release lifecycle.
Backend Placement
Use the owning layer:
- validators parse params, queries, bodies, environment, and persisted untrusted input;
- repositories own organization-scoped CRUDL and transactions;
- services/helpers compose lifecycle behavior;
- controllers own one request-facing operation per named function;
- routes bind middleware and handlers;
- application modules assemble startup and shutdown; and
- documentation modules own OpenAPI paths and examples.
Do not put request behavior in routes or domain behavior in server assembly.
Runtime Preferences
Prefer Bun and Web APIs. Use Bun-supported compatibility modules only when needed. Do not add
node: specifiers or NodeJS namespace types. Validate environment once and inject dependencies in
tests.
Baseline Commands
bun install --frozen-lockfile
bun run check
bun test
bun install --cwd sites --frozen-lockfile
bun run --cwd sites checkbun run check is product-only. Use bun run check:all to check both dependency roots. Run the
affected app or package typecheck during implementation, then the complete relevant suite before
committing.
Worktree Discipline
- Preserve unrelated user changes.
- Stage exact files for each semantic commit.
- Review
git diff --cached --name-statusbefore committing. - Keep commits aligned to one completed extension or documentation checkpoint.