Use the root README for installation and local startup.
The runtime requirements are in package.json and
server/go.mod; workspace library versions are pinned in
pnpm-workspace.yaml and the lockfile. Install with
pnpm install --frozen-lockfile. Browser checks use Playwright Chromium;
pnpm --filter @atape/web exec playwright install chromium installs it locally.
Package terminal checks require Python 3. PostgreSQL and installed source-capture Adapter
integration checks require Docker.
| Area | Responsibility and entry points |
|---|---|
| apps/web/src | view renders, presenters bind intents and ViewModels, runtime provides Browser Adapters and Layers |
| apps/cli/src | entry.ts validates the bootstrap launch and delegates to the selected managed version; main.ts composes the executable and owned Collector/updater entries; commandInput.ts decodes command input; commands.ts and interactive present the CLI; runtime owns Node Adapters |
| packages/application | Effect Modules for client management, collection, capture, publication, recovery and reader workflows |
| packages/domain | Shared domain types, Schemas and pure rules |
| packages/adapter-catalog | Shared official-tool metadata |
| packages/ui and packages/i18n | Reusable presentation, semantic themes and localization support |
| adapters | Codex, Claude, OpenCode, CodeBuddy, Kimi, Grok and experimental Cursor provider Implementations; the Host loads their declared runtime capability |
| server/internal | Go Modules for authentication, authorization, Team, Canonical ingestion, publication, conversation, Session Analytics, Raw and Search; private infrastructure under adapters |
| server/cmd/atape-server | Server Composition Root and process lifetime |
| specs, scripts and workflows | Machine-readable contracts, verification, packaging and delivery gates |
These are existing ownership boundaries, not a template for adding pass-through Modules. The architecture manual defines the rules; the documentation index routes to feature-specific contracts.
Choose checks for the changed Interface and its consumers. Examples below are
starting points for local work; they do not replace required integration or
release gates. Use the package's test script with a test path to focus a
regression when appropriate.
| Changed area | Relevant local checks |
|---|---|
| Documentation only | pnpm check:docs and git diff --check, plus review of status claims; for release guidance also run pnpm test:release:gates |
| TypeScript Module or import boundary | pnpm check:architecture; affected package typecheck and test, e.g. pnpm --filter @atape/application typecheck and pnpm --filter @atape/application test |
| Web behavior | pnpm --filter @atape/web typecheck, pnpm --filter @atape/web test, and affected test:browser scenarios |
| CLI commands or terminal behavior | pnpm --filter @atape/cli typecheck, pnpm --filter @atape/cli test, pnpm test:cli-package for the installed executable |
| Adapter projection or package/runtime contract | Affected Adapter typecheck and test; pnpm test:adapter-package for installed artifacts |
| Collector / Server delivery | pnpm test:e2e for Codex against the demo Server; pnpm test:claude-contract, pnpm test:opencode-contract, pnpm test:codebuddy-contract, pnpm test:kimi-contract, pnpm test:grok-contract and pnpm test:cursor-contract for installed Adapters over authenticated HTTP/PostgreSQL. Claude requires both current sourceCapture and genuine previous-main legacy contracts; the runner freezes that artifact automatically. |
| Go Module | From server/, go test ./internal/<module>/...; use pnpm test:go:integration for persistence and authenticated boundaries, and race/fuzz checks when affected |
| SQL migration or query | pnpm generate:sqlc, inspect generated changes, and run affected PostgreSQL integration checks |
| Compose or backup/restore | pnpm test:self-hosting:config; pnpm test:self-hosting:restore for paired recovery in isolated containers/volumes |
| Packaging or publication | Release verification and gates |
pnpm check runs documentation and architecture checks, workspace typechecks and tests,
Web browser tests, Codex/Claude E2E and Go unit suites. It does not include every
release or PostgreSQL check. pnpm test:go:integration also runs installed
Claude, OpenCode, CodeBuddy, Kimi, Grok and synthetic Cursor contracts; its name is narrower than its coverage.
The Go installed-Collector contracts pack existing production dist outputs
with npm lifecycle scripts disabled. Run pnpm build after implementation
changes before invoking those local contracts so the packaged Host and Adapter
match the source being verified.
Genuine historical Claude and capture-journal fixtures install their pinned revision's dependency lock in an isolated temporary workspace and verify source and toolchain provenance. They never borrow current dependencies. Installation tries the local package cache first; a cache miss requires registry access. The historical fixture's success is separate from current-runtime acceptance.
pnpm check:docs parses Markdown links and headings, checks local file/anchor
targets, concrete pnpm script names and documentation/ADR index coverage. It
checks links in historical documents while preserving their old command examples.
External links are not fetched, and passing this check does not establish that
prose matches product behavior. Reader response schemas are additionally compared
with the exported Go JSON types by the HTTP contract tests.
CI additionally verifies Web rollout/rollback, production builds, release tarballs, PostgreSQL/installed source-capture Adapter contracts and Collector disk-exhaustion recovery. Security and Release define their additional gates. Read the workflows and package scripts when their exact scope matters.
After the relevant checks pass, repeat or broaden them only for new changes, failures or unresolved risk. Report missing prerequisites and checks not run; local success is not evidence that CI or manual staging passed.
Preserve concurrent work and update the affected feature guide. For an integration
request, start from the latest main, reconcile ADR/migration numbers and generated
code, and land one usable increment through required PR checks before expanding
the next. Keep research binaries and private transcripts out of implementation
commits. Record architectural exceptions in an ADR before implementation.
Merging, package publication and Server deployment are distinct actions. The
dogfood Web already has an automatic deployment workflow
after successful main checks; account for that existing effect when integrating.
Publication requests follow ADR-0048
and the release guide.