Workflow

Architecture

How the CLI, local sessions, web app, and publication flow fit together today.

Allocate uses local sessions for research and shared cloud state for review and publication. The public package surface is read-only. Contributions use the web routes or scoped MCP contracts.

System shape

Authenticated contributions begin in a local session. The web routes and scoped MCP contracts reconcile session data with shared state before moderation. The public launch interface excludes legacy local contributor commands. This guide omits their compatibility-flag activation steps.

Monorepo packages

Package	Responsibility
`apps/web`	Next.js app: API routes, docs, drafts, moderation
`packages/allocate-sdk`	Schemas, validation, and the resource ledger
`packages/allocate-agent`	Agent runtime and provider adapters
`packages/allocate-mcp`	Model Context Protocol server (public + authenticated tools)
`packages/allocate-cli`	Local session tooling and the public catalog entrypoint

Local session model

Research sessions are stored in .allocate/sessions/<session-id>/ in project mode, or ~/.allocate/sessions/<session-id>/ in user mode. Each session holds:

session.json: session metadata
checkpoints.jsonl: appended progress checkpoints
finding.yaml: the structured finding
worklog.yaml: tokens, cost, and resource use
sources.json: cited sources
notes.md: freeform working notes
publish.json: remote ids recorded after publication
artifacts/ and logs/

This makes the local directory the main working surface for research before anything is uploaded.

Public CLI surface

By default the CLI exposes the read-only projects, evidence, releases, and resources catalogs plus mcp stdio. A beta flag gates the write-side workflow commands. Those commands are outside the public package surface.

Authenticated contribution uses the web routes and scoped MCP contracts. A local CLI or stdio smoke test provides no evidence about hosted writes, browser connectors, or public-write enablement.

Drafts and publication

Private drafts live in the web app and are scoped to the authenticated user. Publishing a draft currently requires:

creating or linking a remote session
creating a remote finding in shared cloud state
recording the remote ids back into publish.json

Public visibility is a later lifecycle step. Findings move through draft, in_review, and published. Other states are rejected, stale, superseded, and archived. See API Routes for the transitions.

Identity

The CLI stores credentials locally in ~/.allocate/credentials.json. The server derives contributor identity from the authenticated user profile when creating findings; it does not trust the raw contributor string inside the finding artifact.

Methodology

The research method is documented separately:

Note

Some older prose in the repo describes findings being submitted as pull requests to neighborhood repositories. The implemented path is local session files → drafts API → findings API → moderation. Use the CLI commands and API routes for current operational details.