Release surfaces
The surfaces.json manifest and its four release roles, Core and Enterprise for both Pi and Claude Code, which enforce the split at build time.
Every Pocketto release is built from an explicit manifest (surfaces.json, schema SURFACE_MANIFEST=1) which defines exactly four roles:
| Role | Host | Contents |
|---|---|---|
pi/core | Pi | Local-first Core workflows and neutral lifecycle CLI (including Education) |
pi/enterprise | Pi | Additive Enterprise adapter and references; requires pi/core |
claude/core | Claude Code | Local-first Core workflows and neutral lifecycle CLI (including Education) |
claude/enterprise | Claude Code | Additive Enterprise adapter and references; requires claude/core |
Release builds stage an explicit role with:
node scripts/build-surfaces.js --role <role> --output <artifact-dir>The staged directory contains only the selected role.
The additive-delta principle
An Enterprise stage is an overlay on the matching Core stage:
- It includes only adapter-owned files: the
enterprise/modules, thepocket-enterpriseandcreate-prskills, the Enterprise reporting reference for development, and the lazymode/formatCLI commands. - It does not bundle or copy Core skills and does not include Core entry points such as
cli/index.js. - It requires its matching Core role at runtime.
Enforcement
Each role declares includes, requires, forbidden_paths, and forbidden_content:
- Core roles forbid the Enterprise paths (
enterprise/,skills/create-pr/,skills/pocket-enterprise/, the Enterprise reporting reference,mode/formatcommands), and forbid the content strings that would leak Enterprise behavior into a Core artifact. - Enterprise roles forbid Core entry points (
cli/index.js,log/logjsoninternals,pocket-help,pocket-planning). The delta cannot become a standalone product.
An ownership map (ownership) declares each path as core, enterprise, or shared (the reconcile command and identity helpers), and the cli_boundary section documents that Core starts without the Enterprise-only modules: mode/format load lazily through the boundary.
What this means for you
- Install Core alone and nothing Enterprise-flavored can reach you: not by convention, by construction.
- Add Enterprise and you get only its delta: your Core install stays canonical; never copy a Core skill to add remote behavior.
- The npm package (
pocketto-pi) contains both Core and Enterprise sources so either role can be staged from it; it is not itself a Core-only tree.
Related documentation
Lifecycle state
The shapes of log.json and lifecycle.json, the task and phase state transitions, and the rule that only the Pocketto CLI writes these files.
Troubleshooting
Pocketto error codes grouped by area, each with its recovery route, from CLI contract mismatches and plan structure errors to Enterprise PR blockers.