circular

name	circular
description	Work effectively inside the Circular codebase, a MoonBit local-first personal learning/research workspace. Use when editing or reviewing Circular product docs, MoonBit domain/backend/storage code, Rabbita frontend code, SQLite persistence, the local agent CLI, focus sessions, inbox/project/task workflows, or when an agent needs project-specific commands and design constraints.

Circular

Start Here

Treat Circular as a personal, local-first learning workspace, not a team project manager. Before non-trivial code changes, read AGENTS.md and skim docs/Design.md if it exists in the workspace.

Use the moonbit-agent-guide skill as the MoonBit language companion when working in .mbt files.

Product Principles

• Keep the workflow centered on Capture -> Clarify -> Plan -> Do -> Learn -> Review -> Continue.
• Prefer personal learning language over team delivery language.
• Follow correct-by-construction design: parse at boundaries, then pass stronger domain values such as refs/witnesses into domain operations.
• Do not add fake boundary types, generic traits, repositories, command buses, or validation layers unless they remove real repeated logic.
• Keep core semantic and typed; keep JSON/HTTP/frontend payloads in syntax.
• Treat SQLite and HTTP as untrusted boundaries. Re-parse data into domain invariants before acting.
• Focus sessions record execution intervals. They may move a task to Doing, but must not auto-complete the task.

Package Map

• core/: domain model, WorkspaceState, ids, invariants, focus/session logic.
• syntax/: JSON-friendly command/view syntax and WorkspaceCommand.
• storage/: SQLite schema, loading, saving, snapshot recovery.
• cmd/circular-server/: local backend, /api/workspace, /api/fn/*.
• cmd/circular/: agent CLI wrapper around backend functions.
• agent/: CLI summaries/context formatting.
• web/: Rabbita app assembly.
• web/state/: frontend model, drafts, choices, selections, modal state.
• web/effect/: HTTP effects and endpoint definitions.
• web/updater/: Elm-style update logic and side-effect orchestration.
• web/component, web/modal, web/page, web/task, web/focus: view and feature helpers.

Working Loop

1. Inspect package boundaries with rg --files and nearby moon.pkg files.
2. Read existing patterns before adding abstractions.
3. Keep edits package-local when possible; MoonBit files inside one package share declarations, so split large files freely by responsibility.
4. Use ///| block separators in MoonBit files.
5. Prefer methods for behavior owned by a type, labelled args for same-typed fields, pattern matching over tiny boolean helper chains, and raise DomainError for domain failures.
6. After edits, run moon info && moon fmt, then check .mbti diffs for intended public surface changes.

CLI For Agents

Start the backend:

pnpm run dev:server

After pnpm run install:cli, agents can start the installed backend with:

circular server start

Stop a managed background server with:

circular server stop

server stop first uses the local admin shutdown endpoint with the generated control token, then falls back to pid-based SIGTERM if needed.

Use circular server run instead when the agent environment cleans up background children and you need a foreground long-running server session.

Run the CLI without installing:

pnpm run agent -- help
pnpm run agent -- workspace --raw
pnpm run agent -- continue

Install it when repeated testing is useful:

pnpm run install:cli

This builds the frontend, installs circular and circular-server, and copies the static app into ~/.circular/web. Raw moon install only installs MoonBit binaries, so it is not enough for the browser UI.

After circular server start, the browser app is served from http://127.0.0.1:4873/; /api remains the functions endpoint.

Default backend URL is http://127.0.0.1:4873. Override with --api URL or CIRCULAR_API.

Default local storage is ~/.circular/circular.db. Override with CIRCULAR_DATA_DIR or CIRCULAR_DB. Frontend assets default to ~/.circular/web; override with CIRCULAR_WEB_DIR.

Common command shapes:

circular capture --text "raw thought" --kind idea
circular clarify project --inbox IN-1 --title "Learn Rabbita"
circular clarify task --inbox IN-1 --project PRJ-1 --title "Read docs" --content "Take notes"
circular task create --project PRJ-1 --title "Build slice" --content "Ship one vertical flow"
circular task subtask TSK-1 --title "Write test" --content "Cover tree rendering"
circular task state TSK-1 doing
circular task priority TSK-1 high
circular task energy TSK-1 deep
circular focus start TSK-1 --focus 45 --break 5 --intention "One focused interval"
circular focus finish FOC-1 --reflection "Shipped the first pass"

Use circular fn NAME --stdin for exact JSON payloads against /api/fn/NAME when the typed CLI surface is not enough.

Current id prefixes: IN-*, PRJ-*, TSK-*, FOC-*, Q-*, REV-*.

Frontend Taste

Build a quiet, dense, responsive personal workspace. Linear/Plane are references for clarity and object stability, not for team-process ceremony.

• Avoid marketing hero layouts and decorative dashboard noise.
• Prefer compact rows, stable toolbars, clear modal forms, and readable information hierarchy.
• Keep dark/light mode coverage complete when touching styles.
• Use the Browser plugin for visual verification after significant UI changes.
• Check narrow viewports; horizontal page scroll and overlapping controls are regressions.

Validation

Use the smallest useful loop during implementation, then finalize with:

moon info
moon fmt
moon check --target all
moon test --target all
pnpm build

Expected known warnings may include Rabbita experimental API warnings and Vite large chunk warnings from editor dependencies. Do not ignore new type errors, test failures, unexpected .mbti changes, or UI regressions.

Local Data

~/.circular/circular.db is the default local database. A repo-local circular.db may still appear in old test runs and is ignored. Cleaning either database may require stopping the running backend first. Never commit databases, dist/, node_modules/, _build/, or .mooncakes/.