pm-presets

Requires pm CLI 2026.10.25 or newer for complete artifact reconciliation and owned settings replacement.

All 7 official pm-cli workspace presets in one package.

Install once, get all preset setup commands:

pm install github.com/unbraind/pm-presets --project

Available Presets

Preset	Command	Governance	Best For
bug-triage	pm triage-setup	custom strict-close	Incident response, triage teams
indie-dev	pm indie-setup	minimal	Solo developers, personal projects
open-source	pm oss-setup	standard	OSS maintainers with community contributors
software-sprint	pm sprint-setup	standard	Engineering teams running sprints
startup-roadmap	pm roadmap-setup	custom	Startups with investor-facing roadmaps
kanban	pm kanban-setup	minimal	Continuous-flow boards with a custom Card item type
agent-workflow	pm agent-setup	default	AI agent project management with a custom AgentRun item type

Run pm presets list for the full, machine-readable catalog.

Usage

1. Initialize a pm workspace in your project:

   pm init
   

2. Apply a preset:

   pm triage-setup        # strict bug triage
   pm indie-setup         # minimal solo dev
   pm oss-setup           # open-source project
   pm sprint-setup        # software sprint
   pm roadmap-setup       # startup roadmap
   pm kanban-setup        # continuous-flow kanban
   pm agent-setup        # AI agent project management
   

All setup commands share the same flags:

Flag	Short	Description
--force	-f	Reconcile changed preset templates and managed seed contents
--dry-run	-n	Preview artifacts; the host audit may create a lock file
--prefix	-p	Override the id_prefix in settings.json
--param <name>=<value>		Supply a declared preset parameter (repeatable; see Preset parameters)
--params-file <file>		Read parameter values from a JSON object file

Each setup command installs valid pm create templates and registers the templates show runtime handler required by the current pm CLI, so pm create --template <name> works after installing and applying this package.

Managing presets

Beyond the per-preset *-setup aliases, pm-presets ships a unified, read-only management surface plus a generic apply:

Command	Description
pm presets list	Enumerate every bundled preset and what it configures (governance, built-in + custom item types, templates).
pm presets show <id>	Print the full definition of one preset: the settings patch it merges, every template (with its pm create option keys), and any custom item types it registers.
pm presets diff <id>	Compare the current workspace (settings.json + installed templates) against a preset and report what apply would add / change, including missing or changed complete templates and managed seed contents. Add --strict to exit non-zero on drift (CI/compliance).
pm presets plan <id>	Negotiate operational prerequisites before mutation; use --composition and --target for composed/provider plans. Missing required contracts exit 2.
pm presets stack --input stack.json	Preview a canonical preset stack; conflicting settings, templates and seed identities require explicit owner choices.
pm presets validate	Validate that all bundled presets parse and load coherently (governance enums, template names/options, registry↔export agreement).
pm presets apply <id>	Scaffold a preset into the current workspace (the generic form of the *-setup commands). Add --replace for a clean reset of the owned settings trees.
pm presets export <name>	Snapshot the current workspace's settings + templates as a reusable preset definition (JSON), to stdout or a file.

All of the read-only commands accept --json for machine-readable output, and all commands accept --help. An unknown preset id exits with code 3 (NOT_FOUND).

pm presets list
pm presets show software-sprint --json
pm presets diff software-sprint           # what would change if I applied it?
pm presets diff software-sprint --strict  # exit 4 if the workspace has drifted
pm presets validate
pm presets apply software-sprint --dry-run
pm presets apply software-sprint --replace  # clean reset of governance/validation/testing
pm presets export our-config --output our-config.preset.json

Unified presets flags

The bare pm presets command offers a single entry point for the read-only surfaces via flags (the dedicated subcommands above remain available with identical behavior):

Flag	Description
--list	List all bundled workspace presets (same output as pm presets list).
--diff <id>	Compare the current workspace against the named preset (same as pm presets diff <id>); accepts --strict and --json.
--custom <name>	Export the current workspace config as a new preset definition (same as pm presets export <name>); accepts --output, --display-name, and --json.

pm presets --list
pm presets --diff software-sprint --strict
pm presets --custom our-config --output our-config.preset.json

Specify exactly one of --list, --diff, or --custom per invocation.

presets apply flags

presets apply accepts the shared --force / --dry-run / --prefix flags, plus:

Flag	Short	Description
--with-seeds	-s	Enroll the preset's starter items as managed artifacts, creating missing items and reconciling them with later bindings.
--replace		Full-replace the governance / validation / testing trees with the preset's instead of deep-merging them.

Idempotency & safety. apply is safe to re-run:

• Requires the host pm CLI minimum declared in manifest.json and the package peer dependency. Settings changes use the host-bound SDK audit lock and workspace history. Application awaits that commit before writing templates or creating seeds; an unavailable audit capability fails closed.
• settings.json is deep-merged by default — the preset's keys are layered over your existing settings, so unrelated config (telemetry, locks, etc.) is preserved.
• --replace instead swaps the governance / validation / testing trees wholesale with the preset's trees — resetting omitted keys to host defaults and deriving named governance policies, for a clean reset. The host serializer preserves unrelated top-level settings. Omitted raw keys inside the three replaced trees are removed. Unowned top-level settings (telemetry, locks, …) remain preserved in both modes; the preset still sets id_prefix.
• Existing templates are skipped only when their complete JSON documents already match. A non-force apply that would leave changed templates or managed seeds returns stale_artifacts (exit 2), naming their relative paths, before changing settings or history. Inspect the changes and use --force to reconcile them.
• Apply and diff share one desired-state planner for settings keys, complete template documents, managed seed content and seed ownership. A successful real apply verifies that complete postcondition before reporting success.
• --dry-run previews every settings merge/replace, template write, and seed item without writing workspace settings, templates, items or history. The host may acquire an audit lock; replacement normalization uses isolated public settings.

Drift detection: presets diff --strict

presets diff <id> --strict reuses the diff logic but exits non-zero (code 4) when any managed artifact differs: settings keys, full template JSON documents (including options and metadata), or managed seed contents. It prints what drifted (human summary, or the full diff with --json) before exiting, so CI logs explain the failure. When the workspace already matches the preset it exits 0. Plain presets diff (without --strict) reports structured drift with templates.changed, seed missing/changed entries and an artifacts list of relative paths. Both diff forms accept --prefix, --replace and --with-seeds to mirror application choices. Invalid inputs still refuse with a typed error. Unreadable artifacts remain named drift and can never produce a synchronized result.

# Fail a compliance/CI job if the workspace drifts from the locked preset:
pm presets diff bug-triage --strict || echo "workspace drifted!"

Exporting your own config: presets export

After you apply a preset and customize it, presets export <name> captures the live workspace as a reusable preset definition (settings.json plus every installed template). Write it to stdout (use --json for clean, pipeable output) or to a file with --output:

pm presets apply bug-triage          # start from a bundled preset
# ...customize settings.json and templates by hand...
pm presets export our-config --output our-config.preset.json --display-name "Our Team Config"

The exported document is $schema: "pm-presets/exported-preset@1" and records settings + templates. Workspace-local preset_artifacts ownership is excluded; a portable preset cannot adopt another tracker's item ids. Custom item-field values are not captured: custom scalar fields have no pm create --<field> setter today (pm-cli #97), so the snapshot reconstructs the preset from settings + templates only.

Managed seeds. --with-seeds uses the host SDK client and active schema; it needs neither a pm executable on PATH nor git. Stable preset/slot item ids are recorded in settings.preset_artifacts and recovered from the host's verified append-only workspace audit. Removing the settings record cannot hide stale or missing seeds from diff. Older unmanaged starter items are not adopted implicitly. Once enrolled, later applies and diffs include those seeds even without repeating --with-seeds; prefix changes keep their established ids and update the controlled type/title/priority/tags/body and explicit no-parent state. Existing item lifecycle and unrelated user metadata remain host-owned. Reapplying matching content creates no duplicate seeds. Seed plans use the native writer's type aliases, trimmed titles, named priorities, canonical tag lists and body normalization. Equivalent authored values therefore agree across apply, strict diff, stack previews and prerequisite plans.

Settings, template and seed writes share one apply admission. A preflight checks overwrite conflicts before settings/history mutation. Native write failures exit nonzero; completed audited writes remain recorded, and retrying reconciles artifacts that were never written. Template ownership is recorded after the whole template write succeeds, so a template written before a later failure in the same run is unowned: a retry refuses it with artifact_conflict until you preserve, rename or remove it. Seed reads use the SDK locator/parser and emit no usage/cache writes.

Seeds and custom fields. Starter items created by --with-seeds set only built-in fields (type, title, priority, tags, body). Custom scalar fields registered via registerItemFields still have no direct pm create --<field> setter, so seed-only context lives in the item body. Registered item-type options are supported through --type-option: the agent-workflow templates persist phase, mode, and model this way while leaving the core pm status field untouched. The kanban Card and agent-workflow AgentRun seeds are created with their registered item types.

Preset parameters

A preset can declare typed parameters once in a manifest and reference them with ${param:<name>} binding occurrences in its settings patch, template options and seed items. One supplied value then reaches every declared occurrence — the startup-roadmap preset, for example, uses its projectKey parameter for the id_prefix, the roadmap template prose, and its starter initiative seed:

# Default resolution (projectKey defaults to "road"):
pm presets apply startup-roadmap

# Inspect the changed templates before reconciling owned artifacts:
pm presets diff startup-roadmap --param projectKey=acme
# One supplied value reaches every occurrence (prefix becomes "acme-",
# templates record "acme" under "## Project", the seed title names the acme project):
pm presets apply startup-roadmap --param projectKey=acme --with-seeds --force

# Values can also come from a JSON file:
pm presets diff startup-roadmap --params-file params.json
pm presets apply startup-roadmap --params-file params.json --force

pm presets show <id> lists every declared parameter (type, constraints, default, and whether it is still unanswered), and presets diff <id> accepts the same --param flags so the drift preview resolves exactly like a parameterized apply.

Refusal contract. All parameter input is validated once, before anything is read or written, with typed exit-2 refusals:

• an unknown supplied name (--param ghost=1) is refused (unknown_parameter);
• a required parameter with neither a value nor a default is refused and every unanswered choice is listed (unanswered_parameter) — by apply and by a parameterized diff, while show keeps displaying the declaration;
• values that violate the declared pattern, enum or length bound are refused (invalid_value); control characters and line breaks never enter prose;
• joining values or surrounding text must not assemble new ${param:...} syntax (invalid_value); parameter substitution never evaluates generated bindings;
• a binding that references a name the preset never declared is an authoring error and refuses (unknown_binding), as does a malformed ${param:...} fragment (malformed_binding);
• all manifests validate bindings, including an explicit empty parameters: []; unresolved or malformed occurrences refuse before settings or template writes.

Secrets. A secret parameter accepts only an external environment reference, for example --param token=@DEPLOY_TOKEN. Literal credentials are refused with invalid_secret_reference (exit 2); keep values in the environment, never in a params file or tracker. Secret defaults are forbidden.

Secret-reference bindings must occupy an entire value in the explicit settings.secret_references.<name> map, for example secret_references: { deploy: "${param:token}" }. That map stores pointers only; it cannot receive credential values. Identifiers (id_prefix, seed IDs), titles, tags, filenames, templates and other settings are public tracked data; secret bindings there refuse at manifest projection, even without a supplied value. References cannot be interpolated into a larger string.

Reference maps preserve accepted JSON names, including __proto__ and constructor, through resolution, previews and audited storage. Once a reference map exists, the host audit protocol cannot add or change its __proto__ entry. Such updates refuse before writes; keep a stable reference and rotate the external environment value. Public templates and seeds require nonempty trimmed field names and refuse __proto__ before writes because supported host readers lose that field. Existing templates that would lose option names refuse reads/exports with a typed remedy instead of returning partial data.

Apply stores only @DEPLOY_TOKEN, including in audited append-only history. Dry-run, diff and parameter summaries display references, never credentials. Static references such as secret_references: { deploy: "@DEPLOY_TOKEN" } receive the same protection: diffs hide legacy credentials at those destinations. SDK callers retain known legacy sensitivity in WorkspaceSnapshot.secretSettingPaths. Diff combines those stored paths with incoming provenance before comparing: sensitive prefixes refuse managed seed comparisons, and sensitive governance, validation or testing paths refuse --replace with invalid_secret_reference. Ordinary comparisons redact both sides of those locations, including when their JSON shapes differ. Show may retain the authored occurrence for an unanswered declaration. Commands do not read credential environment variables. A consuming integration calls resolveSecretReference("@DEPLOY_TOKEN") only when the credential is needed; that API returns the current environment value in memory without logging or writing it. Missing or empty variables produce a privacy-safe typed refusal. Rotating the external value requires no tracker change. There is no automatic migration or rewrite of credentials already stored by older versions: revoke those credentials and review affected tracker history separately.

Defaults and supplied public values share trimming and constraint checks; seed previews resolve defaults before computing identities and ownership.

One resolution, one read. The unified apply reads your flags and params file exactly once, resolves every parameter at that boundary, pre-validates the preset's seed bindings, and threads the same effective values through the settings merge, the template writes and the seed creation — editing the params file mid-apply cannot split your workspace across two values.

Ownership and recovery. Existing item ids, template names and customized settings are preserved unless recorded preset provenance proves ownership. Upgrading: workspaces configured by earlier pm-presets versions carry no provenance. Their templates and customized settings are unowned, so the first re-apply with this version refuses them with artifact_conflict, even when the contents match. Move or remove those templates and reset customized leaves before that apply, or keep the current configuration and only run pm presets diff. --force reconciles owned drift; an unowned collision returns artifact_conflict with its exact id or path. A missing managed seed with retained history returns artifact_recovery_required with a native pm restore <id> <timestamp> command for its latest verified materialized state. Run that command, inspect the restored item and retry; keep the history. Ownership metadata stays workspace-local and is omitted from exported presets.

Concurrent applies. A real apply holds a workspace-scoped lock (.agents/pm/locks/) across the audited settings mutation and the template writes, so two concurrent parameterized applies can never leave the id prefix of one invocation next to the template prose of another. Dry-runs skip the preset apply lock. The host audit may create its own lock file and may refuse on a read-only tracker. Dry-runs do not change preset artifacts.

Publication, stale recovery and release also hold an admission claim with a unique per-process pathname. Cleanup targets that exact claim, so a delayed reaper cannot unlink a replacement owner's claim. Live owners are never evicted because of age. Automatic recovery requires a verified kernel/PID namespace and a PID proven absent; unverifiable claims stay locked. Inspect abandoned claims only after confirming their writers have stopped.

--params-file reads one regular JSON file, bounded to 64 KiB even if it grows while being read. Missing, unreadable, nonregular and oversized files return invalid_params_file with exit 2, without raw filesystem diagnostics.

The same engine backs every read path (show, diff, plan, stack, validate): answered bindings resolve in every preview, while a declaration-mode projection may keep the authored ${param:...} occurrence for an unanswered parameter. See docs/params-example.md for the full authoring walkthrough.

Presets in Detail

bug-triage

Governance: custom strict-close — progressive creation with strict ownership and close validation.

Templates: incident, hotfix-task, regression

Default id_prefix: bug-

Best for on-call teams and incident response workflows that need full audit trails.

pm triage-setup
pm create --template incident
pm create --template hotfix-task
pm create --template regression

indie-dev

Governance: minimal — no required fields, no ownership enforcement.

Templates: idea, task

Default id_prefix: indie-

Best for solo developers who want lightweight task tracking with zero ceremony.

pm indie-setup
pm create --template idea
pm create --template task

open-source

Governance: standard — structured without blocking community contributors.

Templates: bug-report, feature-request, good-first-issue

Default id_prefix: oss-

Best for open-source maintainers handling community submissions and milestone releases.

pm oss-setup
pm create --template bug-report
pm create --template feature-request
pm create --template good-first-issue

software-sprint

Governance: standard — sprint format validated, ownership warned.

Templates: epic, feature, task, bug

Default id_prefix: sprint-

Best for engineering teams running two-week sprints with epics and features.

pm sprint-setup
pm create --template epic
pm create --template feature
pm create --template task
pm create --template bug

startup-roadmap

Governance: custom with rich metadata — captures business value and strategic context.

Templates: initiative, feature, milestone

Default id_prefix: road-

Best for startups building investor-facing roadmaps with quarterly planning.

pm roadmap-setup
pm create --template initiative
pm create --template feature
pm create --template milestone

kanban

Governance: minimal — continuous flow with light ownership warnings.

Templates: card, expedite, blocked

Default id_prefix: kan-

Best for teams that pull work through backlog, ready, in-progress, review, and done columns.

pm kanban-setup
pm create --template card
pm create --template expedite
pm create --template blocked

Migration from legacy individual preset packages

If you previously installed individual preset packages, uninstall those legacy entries shown by pm package list --project and install pm-presets instead:

pm package list --project
pm package uninstall <legacy-preset-package> --project
pm install github.com/unbraind/pm-presets --project

The preset commands are identical — only the package name changed.

Preset setup handlers and applyPreset return Promise<void>; await their completion before reading the updated configuration. Dry runs validate against locked current settings and display a labeled preset patch without writing settings or history. The host derives governance policies and canonical storage; the patch is a proposed change, rather than a serialized final settings tree. Replacement previews also list omitted existing owned trees and keys that the host resets to defaults or preset policy, without printing their old values. Templates are separate filesystem writes after the audited settings commit; a later filesystem failure does not roll back that committed settings event.

Simulate before applying

Run representative agent workflows before changing your workspace:

pm presets simulate bug-triage
pm presets simulate indie-dev --json
pm presets simulate software-sprint --scenarios create-task,claim-start --json

Suite version 1 applies the same bundled setup handler as presets apply, then executes four workflows with the real local pm SDK:

Scenario	Declared result
create-task	Task exists and is open
claim-start	Claimed Task is in progress
close-without-evidence	Refused for bug-triage; closed for other bundled presets
close-with-evidence	Closed with resolution, expected and actual result

Expected governance refusals count as passing observations. Every report includes expected and actual states, pass counts, omitted scenario IDs in coverageGaps, and scope limitations. Selecting a subset does not establish full coverage. Exit 4 means a mismatch or coverage gap; the report is printed before the error. Unknown presets/scenarios and duplicate selections produce typed usage refusals (exit 2) with remedies. Missing SDK support or worker failure uses exit 1.

The simulator accepts bundled IDs and scenario IDs only. It creates a new tracker and home directory in a separate process, disables extension loading and telemetry, and supplies no tracker paths, credentials, scripts or caller configuration to it. It never installs into, reads, or writes the caller's tracker. Scratch files are removed after success or failure. The CLI host may perform its normal runtime bookkeeping before invoking an extension command.

Reports are reproducible for the same package, suite and supported host version: random item IDs, timestamps, paths, durations and free-form SDK diagnostics are excluded. Scenarios run in canonical order and each creates its own Task. The bounded suite checks built-in Task lifecycle behavior; installed templates, custom types, external integrations and real agent inference remain explicit limitations. A passing simulation is not approval to apply a preset or a forecast of your workspace's existing policies.

See the SDK example, including partial coverage and handling typed refusals.

Programmatic API

import { PRESET_REGISTRY } from "pm-presets/registry";

for (const preset of PRESET_REGISTRY) {
  console.log(preset.id, preset.command, preset.governance);
}

License

MIT

Multi-agent merge safety

This repo tracks its project management in .agents/pm/ and ships a committed .gitattributes that maps those tracker artifacts to pm-cli's field-aware Git merge drivers, so concurrent-branch tracker edits merge cleanly instead of hard-conflicting. Generated extension assets are excluded from semantic merging, while their managed manifest retains key-level JSON merging. Extension assets use Git's native merge=text attribute. Native text, binary, and union drivers need no merge.<name>.driver registration; the prepare checks require registration for every custom driver and verify native extension text merging in a real checkout. The custom driver definitions live in per-clone Git config; npm install / npm ci wires them automatically via the prepare script, scripts/prepare-merge-driver.ts: a local launcher that delegates to the installed pm-ops export and is tested against an installer behavior contract. It runs pm-ops's installer, which calls pm merge install when the pm CLI is on PATH and skips with a notice when it is not. A production install of a clone (npm ci --omit=dev) has no pm-ops, so the launcher skips with one notice, while a stale or broken pm-ops fails the install. Registry installs of this package never run prepare. Being Node-based, it behaves identically on POSIX shells and Windows cmd.exe. To (re)run manually: npm run merge:install.

After merging a branch that touched .agents/pm/, reconcile any residual history-hash drift with pm merge reconcile: preview with pm merge reconcile --dry-run, apply with pm merge reconcile --message "post-merge reconcile", then confirm with pm validate, which scans the whole tracker and flags remaining history drift across every affected item (pm merge reconcile itself lists each affected stream in its output; pm history --verify <id> spot-checks one item). Reconciliation repairs receipts and history consistency; a successful validation does not prove that every concurrent edit survived. Inspect the merged item values and merge receipts before accepting the result. Keep existing history append-only; do not use history rewriting as a substitute for reconciliation. See the authoritative pm-cli merge-safety guide.

Without git

Preset listing, inspection, diff, validation, export, application, templates and simulation work in plain directories as well as repositories. Simulation always uses a disposable non-git tracker, with no git executable on its PATH. None of these commands requires a Git repository. Upgrade planning, applying, retries and rollback also work without git; they use the host SDK settings lock and history.

Capability plans also work without Git. Database hosts can compile plans from their provider snapshots without a local tracker. Git-based release changelog generation requires a repository and release tags.

Template listing, inspection and export use the host SDK's template inventory and loader. User files shadow builtin names; invalid stored options refuse with the SDK's expected error and a diagnostic that identifies the template and option without echoing document contents. Export uses the loadable filename as its name.

Versioned preset upgrades

pm presets upgrade plan --from vendor-v1.json --to vendor-v2.json --receipt upgrade.private.json compares two {id, version, settings} vendor patches with the current workspace. It preserves local-only edits and requires explicit JSON-pointer decisions when vendor and local changes conflict. presets upgrade apply <receipt> and presets upgrade rollback <receipt> use the host's audited settings API, including idempotent retries and stale-settings checks. Plans and command results use compact TOON or --json; complete recovery settings remain in a private receipt. Requires canonical SDK previews (host 2026.10.17+).

See the complete upgrade example for decisions, recovery, typed SDK usage, refusal remedies and migration boundaries.

Capability-negotiated plans

Run pm presets plan kanban --with-seeds --json before applying a preset. The read-only planner checks the selected provider's operations and the SDK's live workspace contracts. Required gaps produce exit status 2, stable missing_capability codes and remedies; optional features are omitted as a whole. A refused plan never authorizes partial application. No settings, items or history are written by the planner.

Use --composition composition.json for a composed preset with atomic features and --target target.json for the selected directory or database provider's capability and workspace-contract snapshot. The same compiler evaluates both backends. Database hosts supply their actual contracts; the backend label alone never implies support. A snapshot is a planning input, not a connectivity, authorization, schema-validity or transaction guarantee. Replan after provider or extension changes. Existing apply/diff/export and audited replacement remain the execution primitives; this command does not execute composed features.

SDK consumers import compilePresetPlan, bundledPresetComposition, summarizePresetPlan, PlanRefusal and their types from pm-presets. The full SDK plan includes every gap. CLI reports retain complete counts and at most 12 gaps within a 4 KiB detail budget, with omittedGaps showing truncation; host output budgets/projection may reduce output further. Plans contain only contract identifiers and decisions, never settings values or tracker content. See the composed preset example.

Preview preset stacks

pm presets stack --input stack.json --json adapts selected catalog contributions to the host's ProjectProfileDefinition and planProfileApplication. TOON is the default; both formats retain ownership rows and bounded counts without stored settings values, template bodies or seed bodies. Unresolved conflicts return ready: false, code: conflicts, a remedy and exit 2. Identical contributions share ownership; different values at the same identity require a listed owner. Selection order and JSON formatting never determine precedence.

Each selection names a bundled preset. Boolean settings and templates default to true; seeds defaults to false. Disable surfaces to compose disjoint contributions. Settings ownership uses leaf JSON pointers, templates use their name, and seeds use type:title as a catalog identity (not an existing item ID). Choices map each conflicting pointer to a competing preset. Unknown, unused or non-competing choices are refused. Arrays are atomic settings values.

The SDK exports planPresetStack(pmRoot, sdk, input), summarizePresetStack and typed StackRefusal errors. It accepts 1–7 unique selections and at most 128 choices (512 characters per pointer), rejects sparse arrays, unknown keys and non-boolean flags, and bounds CLI JSON artifacts to 1 MiB. Settings previews require canonical includePreview support (host 2026.10.17+). Core plans the registered id_prefix config and templates; other governance, validation and testing leaves use the host's audited dry-run normalization in an isolated, mode-0700 scratch directory with a mode-0600 settings copy, removed in finally. This avoids the host dry-run's workspace lock writes on the source. If normalization would discard an explicit setting choice, normalization_conflict asks for coherent owners. Custom item types/options remain owned by extension activation.

Preview works without git, including on read-only trackers, and writes no source settings, items, templates, history, receipts or journals. Temporary normalization files are removed on success or refusal. There is no stack apply/import/export/sync command. Seed rows describe prospective catalog contributions, without claiming existing items by title. Plans are observations, not transactions or replayable authority; replan after peer changes. Target classifications always read current settings and templates. See the stack example.

SDK callers can await computeDesiredPresetState, computePresetDiff, computeParameterizedDiff and readWorkspaceSnapshot; requirePresetDefinition provides resolved bundled template/seed payloads. JSON and TOON commands use these same APIs. SDK diff requires complete templateDocuments for every declared template and an explicit seedItems inventory for seed comparisons; summary-only definitions refuse. Final overrides and payloads must be resolved. Legacy SDK settings projections remain redacted and cannot report synchronization when application would reject their settings.

Development checks use npm run check for typechecking and npm run lint for compiler-backed unused-local/parameter checks with the pinned TypeScript version.