Installation manifests and schemas
The installation manifest system defines what ECC can install and how users select it. Components present user-facing capabilities, modules group source content for supported targets, and profiles provide named module sets. A validated install-state record then preserves the request, the resolved selection, and the managed file operations for later health checks, repair, update, and removal. See Installation and distribution for the wider install lifecycle and Installer orchestration for the related execution flow.
Manifest model
The manifests form a small selection model rather than a list of individual files. A user chooses a profile, module, or component; the installer resolves that choice into target-compatible modules and records the result as persistent state.
Component manifests
An install component is a user-facing capability with a stable ID, a family, a description, and one or more module IDs. Component families distinguish broad selection areas such as baseline support, languages, frameworks, capabilities, agents, skills, and locales. For example, capability:database exposes the database module while framework:quarkus combines framework guidance with security guidance. (manifests/install-components.json lines 1-16, 125-145)
Components give selection a meaningful product boundary. The catalog also covers platform-specific capability groups such as Itô compute, Nasiko control-plane guidance, translated documentation, and optional documentation change and test workflows. The installer expands each selected component into its modules, removes duplicates, and can filter the component by the targets supported by all of its modules. (manifests/install-components.json lines 158-211, 594-672, 730-744; scripts/…/install-manifests.js lines 371-407, 448-460)
The component schema keeps this public catalog predictable. IDs must use a known family prefix and a lowercase, hyphenated suffix. Each component must have a non-empty description and at least one module reference. (schemas/install-components.schema.json lines 15-54)
References: manifests/install-components.json• L1-16 manifests/install-components.json• L125-145 manifests/install-components.json• L158-211 manifests/install-components.json• L594-672 manifests/install-components.json• L730-744 schemas/install-components.schema.json• L15-54 scripts/…/install-manifests.js• L371-460
Module manifests
An install module is the unit that the installer resolves and installs for a target. It names a kind of content, the source paths that belong to it, the targets that can receive it, its dependencies, and install metadata such as default status, expected cost, and stability. The catalog covers shared rules, agents, commands, hooks, platform setup, skills, orchestration, translated docs, and shared utility support. (manifests/install-modules.json lines 3-29, 31-150, 739-763, 993-1151, 1363-1453)
Dependencies make modules composable. A selected module brings in its required modules, while target support can cause a requested module to be skipped or can prevent a dependent selection from resolving. Optional dependencies may be omitted when the selected target does not support them; supported optional dependencies still install. For example, optional capability modules can depend on common platform or workflow support, while orchestration depends on command and platform support. The resolver also rejects unknown IDs and circular dependency chains. (manifests/install-modules.json lines 239-247, 381-387, 756-762; schemas/install-modules.schema.json lines 70-85; scripts/…/install-manifests.js lines 262-283, 623-685)
The module schema limits the vocabulary for kinds, targets, cost, and stability. It also requires source paths and dependency lists even when those lists are empty. This gives planning and later state checks a complete description of each module. (schemas/install-modules.schema.json lines 10-31, 37-44, 45-93, 95-114)
References: manifests/install-modules.json• L3-29 manifests/install-modules.json• L239-247 manifests/install-modules.json• L381-387 manifests/install-modules.json• L739-763 manifests/install-modules.json• L993-1151 manifests/install-modules.json• L1363-1453 schemas/install-modules.schema.json• L10-114 schemas/install-modules.schema.json• L70-85 scripts/…/install-manifests.js• L262-283 scripts/…/install-manifests.js• L623-685
Profile manifests
An install profile is a named preset of modules for a common installation goal. Profiles describe the intended balance between baseline support and optional capability areas, from the small minimal and core sets through the broader developer, research, security, and full sets. The full profile also tracks newer optional documentation and regression workflows as classified modules. (manifests/install-profiles.json lines 3-108)
Profiles do not replace modules or components. They provide a starting selection that can be combined with explicit component choices and target filtering. The resolver uses a target-specific default profile only when the request does not already name a profile, module, or component; OpenCode therefore starts from its dedicated profile and keeps hooks opt-in. (scripts/…/install-manifests.js lines 145-155, 535-570)
The profile schema requires a version and at least one profile. Every profile must have a non-empty description and at least one lowercase module ID. The schema checks the shape of those references; manifest validation checks whether the referenced modules exist and whether required profiles are present. (schemas/install-profiles.schema.json lines 10-44; scripts/…/validate-install-manifests.js lines 173-215; scripts/…/install-manifests.js lines 262-273)
References: manifests/install-profiles.json• L3-108 schemas/install-profiles.schema.json• L10-44 scripts/…/validate-install-manifests.js• L173-215 scripts/…/install-manifests.js• L145-155 scripts/…/install-manifests.js• L535-570
Synthetic skill components
The selection model also exposes a skill directory as a one-skill component when the directory has no catalog entry. This keeps individual skills selectable without requiring a separate hand-written component entry for every skill. (scripts/…/install-manifests.js lines 170-217)
These generated entries follow the same conceptual model as declared entries: a skill:<id> component points to a skill-<id> module. They are added when manifests load, so tools that list or resolve components see both cataloged and discovered skill choices. (scripts/…/install-manifests.js lines 293-334)
The skill trigger manifest is adjacent metadata for context retrieval, not another install selection layer. manifests/…/skill-triggers@1.json maps some skill IDs to short user phrases and records the registry digest and trigger coverage. The runtime loader accepts only schema version 1, normalizes trigger phrases, and the context-profile validator rejects unknown skills, stale registry data, or a changed trigger digest. (manifests/…/skill-triggers@1.json line 1; scripts/…/context-pack-registry.js lines 128-142; scripts/…/validate-context-profiles.js lines 8-23)
References: scripts/…/install-manifests.js• L170-217 scripts/…/install-manifests.js• L293-334 manifests/…/skill-triggers@1.json• L1 scripts/…/context-pack-registry.js• L128-142 scripts/…/validate-context-profiles.js• L8-23
Selection flow
The selection flow turns user intent into an install plan without treating every request as a raw file copy. It combines named presets and capabilities, applies exclusions, resolves dependencies, checks target support, and returns selected, skipped, and excluded modules.
The relationship between the three manifest levels and the resulting plan is shown below.
flowchart LR
Request[Install request] --> Profile[Profile modules]
Request --> Component[Component modules]
Request --> Module[Explicit modules]
Profile --> Resolve[Resolve dependencies and target support]
Component --> Resolve
Module --> Resolve
Resolve --> Selected[Selected modules]
Resolve --> Skipped[Skipped modules]
Resolve --> Excluded[Excluded modules]
Selected --> Plan[Target install plan]
When an install request is normalized, profile IDs, module IDs, component IDs, locale choices, and legacy language input are kept distinct. Manifest selections cannot be mixed with legacy language arguments, which prevents two different selection models from silently producing one ambiguous plan. (scripts/…/request.js lines 87-150)
The manifest resolver then follows this order:
- Load the module, profile, and component catalogs.
- Add modules from the selected profile, explicit module IDs, and included components.
- Remove excluded components and target-specific default exclusions.
- Resolve each remaining module and its dependencies.
- Mark unsupported target selections as skipped and return the target operation plan.
The resulting plan retains the original selection context as well as the resolved module lists. That distinction lets the system later compare current manifest intent with the state that was installed. (scripts/…/install-manifests.js lines 535-725)
The planning interface makes this model visible without changing a target. It can list profiles, modules, and components, or emit a machine-readable resolved plan for a profile, module set, component selection, and target. (scripts/install-plan.js lines 22-44, 198-268)
References: scripts/…/request.js• L87-150 scripts/…/install-manifests.js• L535-725 scripts/install-plan.js• L22-44 scripts/install-plan.js• L198-268
Schema boundaries
The schemas define the data contract for the catalogs and for persistent state. They make required fields, value types, allowed names, and version markers explicit. They do not by themselves prove that a module reference exists or that a dependency graph can resolve.
Install request schema
The install request schema defines the stable input shape for selecting a target and its capabilities. It accepts one profile, explicit module IDs, component IDs to include or exclude, and an open options object for request-specific choices; it keeps the schema version fixed at 1. (schemas/ecc-install-config.schema.json lines 1-18, 39-71)
The request contract accepts the component families that users can select through the manifest model: baseline, language, framework, capability, agent, skill, and locale IDs. It also permits an explicit target from the supported target set. Reference and dependency checks still occur after schema validation, so a correctly shaped name can still fail if the catalog does not define it. (schemas/ecc-install-config.schema.json lines 18-71; manifests/install-components.json lines 378-486, 594-672)
References: schemas/ecc-install-config.schema.json• L1-71 manifests/install-components.json• L378-486 manifests/install-components.json• L594-672
Context carrier schema
The context carrier schema defines a read-only proposal for carrying selected skills to targets that support a skill layout. It records selection and routing IDs, source and generated files, content digests, and known limits so a proposal can be inspected without changing an installation. (schemas/context-carrier.schema.json lines 1-85)
The schema keeps unsupported targets inactive and file-free. Supported targets must use a known profile and layout, while every file entry must use a safe relative path and a declared digest and size. These rules make the proposal a checked description of possible skill delivery, not a second install-state record. (schemas/context-carrier.schema.json lines 87-105)
References: schemas/context-carrier.schema.json• L1-105
Validation is split across clear boundaries:
| Boundary | Main guarantee |
|---|---|
| Install request schema | Versioned request shape and valid target and component naming patterns |
| Component, module, and profile schemas | Catalog shape, required values, naming patterns, and allowed enums |
| Context carrier schema | Valid read-only skill proposal status, layout, paths, digests, and file forms |
| Manifest loading and resolution | Known references, supported targets, dependency order, exclusions, and cycle checks |
| CI manifest validator | Cross-catalog references, unique IDs, source path coverage, profile coverage, and curated skill coverage |
| Install-state schema and validator | Stable state shape, schema version, target identity fields, request and resolution records, and operation metadata |
The manifest loader reads the three catalogs together and exposes maps for cross-reference. CI then checks relationships that a JSON schema cannot check, including unique IDs, existing and non-overlapping source paths, required profiles, and coverage of curated skill directories. This is why editing one manifest can affect plan resolution or validation even when its JSON shape remains valid. (scripts/…/install-manifests.js lines 293-334; scripts/…/validate-install-manifests.js lines 71-147, 149-245)
References: schemas/ecc-install-config.schema.json• L1-71 schemas/install-components.schema.json• L1-59 schemas/install-modules.schema.json• L1-128 schemas/install-profiles.schema.json• L1-45 schemas/context-carrier.schema.json• L1-105 scripts/…/validate-install-manifests.js• L71-245 scripts/…/install-manifests.js• L293-334
Persistent installation state
Install state is the durable record of one resolved installation for one target. It lets later commands identify what ECC owns, reconstruct the user request, compare the recorded resolution with current manifests, and inspect the health of managed files.
The state has five useful parts beyond its schema version and time fields:
| State area | Meaning |
|---|---|
target | The target identity, target scope, install root, and state-file path |
request | The profile, explicit modules, included or excluded components, legacy mode, hook consent, trust, and MCP consent used by the request |
resolution | Modules selected for the target and modules skipped during resolution |
source | Repository version, commit, and manifest version used for the install |
operations | The managed source-to-destination actions, their strategy and ownership, scaffold status, and optional content hash |
The state schema fixes the format at ecc.install.v1. It requires the target, request, resolution, source, and operations sections and rejects unknown top-level fields. The request can record hook consent, trust, and MCP consent. Operation records allow extra fields so target-specific operation data can remain attached to the common record, while Claude settings updates must identify an approved hook source and target. (schemas/install-state.schema.json lines 1-18, 20-61, 62-128, 130-186, 187-285, 287-313)
State is validated when it is created, read, and written. The validator mirrors the state schema without relying on a separate runtime package, so state consumers can reject malformed or changed records before they use ownership or operation data. (scripts/…/install-state.js lines 4-10, 220-299)
The lifecycle uses the recorded state as a comparison point rather than as a blind truth. It reports missing or changed managed files, missing source files, unsafe operation paths, manifest-version changes, and resolution drift when the current manifests no longer produce the recorded module selection. (scripts/…/install-lifecycle.js lines 1383-1477)
References: schemas/install-state.schema.json• L1-313 scripts/…/install-state.js• L220-299 scripts/…/install-lifecycle.js• L1383-1477
Change checklist
When these files or sections are changed, remember to consider these:
- When a component ID or family changes, review request validation, profile entries, component selections, and user-facing commands that refer to the old ID.
- When a module ID changes, update component references, profile references, dependency references, and any recorded state or migration path that must still be readable.
- When a module target, kind, or dependency changes, review target-specific skips, default exclusions, and the resulting
selectedModulesandskippedModulesstate contract. - When a module path changes, check that the path exists, remains owned by one module, and still covers every curated skill that should ship.
- When a request field or allowed component family changes, keep schemas/ecc-install-config.schema.json aligned with the selection paths exposed by the manifests.
- When a manifest version changes, keep the source version recorded in install state aligned with the value used by lifecycle health checks.
- When a skill description or skill registry changes, regenerate manifests/…/skill-triggers@1.json so its registry digest, trigger digest, and coverage still match the discovered skills.
- When the context carrier schema changes, keep supported target, profile, layout, file, digest, and limitation rules aligned with the producer that creates read-only proposals.
- When the install-state schema changes, update both the schema and the dependency-free validator. Preserve compatibility for existing
ecc.install.v1records or define an explicit migration path, especially for request fields such as hook consent. - When operation fields or path rules change, review repair, update, uninstall, and ownership checks because they use recorded operations as their managed-file boundary.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A profile, component, or dependency names an unknown module | Planning stops instead of producing a partial selection | Manifest loading and resolution check module IDs before use |
| A module points to a missing path or two modules claim the same path | CI rejects the manifests before an install can create an incomplete or ambiguous plan | The manifest validator checks path existence and normalized path ownership |
| A curated skill directory is not covered by a module | The skill is not part of a declared install capability and CI fails | The validator checks each curated skill with a SKILL.md against module paths |
| A selected module does not support the requested target | The module is skipped, or a dependent selection cannot resolve | Target support is checked during dependency resolution |
| Excluding a module required by another selected module | The plan fails rather than silently installing an incomplete capability | Dependency resolution rejects an excluded required module |
| A dependency graph contains a cycle | Planning cannot determine a safe module order | The resolver detects a module already being visited |
| A required profile is missing, or the full profile omits a required non-optional module | The manifest set fails CI and broad installs can miss a declared capability | The validator checks the required profile set and full-profile coverage |
| The skill trigger manifest names an unknown skill, uses an old registry digest, or has a changed trigger digest | Context profile validation fails and trigger-based skill lookup cannot use the checked-in index | Context profile validation compares trigger IDs and digests with the current skill registry |
| Install state has the wrong schema version or missing required fields | State consumers reject it and health status becomes an error | State creation, reads, and writes validate the ecc.install.v1 contract |
| Current manifests resolve differently from recorded state | Health checks report resolution drift and may require review | Lifecycle analysis compares current selected and skipped modules with state |
| A context carrier marks an unsupported target as active or includes files without a valid layout | The proposal fails validation or cannot be safely consumed as a read-only skill plan | Conditional schema rules bind target support to status, layout, and file presence |
Key files
| File | Why to read it |
|---|---|
| manifests/install-components.json | The user-facing capability catalog and its mapping from component IDs to modules |
| manifests/install-modules.json | The installable module catalog, target support, dependencies, and install metadata |
| manifests/install-profiles.json | The named module presets used as common installation starting points |
| schemas/ecc-install-config.schema.json | The versioned request shape for target and capability selection |
| schemas/context-carrier.schema.json | The checked contract for read-only skill carrier proposals and target layouts |
| schemas/install-components.schema.json | The structural contract for component entries and family-based IDs |
| schemas/install-modules.schema.json | The structural contract for module kinds, targets, dependencies, and metadata |
| schemas/install-profiles.schema.json | The structural contract for profile names and module lists |
| schemas/install-state.schema.json | The persistent install-state contract and its stable ecc.install.v1 shape |
| scripts/…/install-manifests.js | The boundary that loads catalogs and resolves profiles, components, modules, dependencies, exclusions, and targets |
| manifests/…/skill-triggers@1.json | The checked-in skill phrase index that supports context retrieval without changing install selection |
| scripts/…/context-pack-registry.js | The boundary that loads discovered skills and validates the trigger metadata used with them |
| scripts/…/install-state.js | The state creation, validation, read, and write boundary |
| scripts/…/install-lifecycle.js | The health checks that compare managed files and current manifest resolution with recorded state |
| scripts/…/validate-install-manifests.js | The CI checks for cross-manifest links, path ownership, profile coverage, and curated skill coverage |
| scripts/install-plan.js | The read-only interface for inspecting available selections and resolved plans |