---
name: cedros-extension-authoring
description: Create, validate, package, test, and publish a Cedros extension without guessing host contracts.
metadata:
  compatibility: "Cedros platform API 1"
  cedros-skill-version: "0.1.84"
  cedros-platform-api-version: "1"
  cedros-index: "https://cedros.ai/skill.json"
---

# Cedros Extension Authoring

Use this public guide to choose the right authoring path and carry an extension
from plan to release. It is stable orientation, not a copy of one deployment's
tool registry.

`MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, and `MAY` are normative. Root-relative
links resolve against the current Cedros host; the canonical public base is
`https://cedros.ai`. Rule IDs and the audit-row contract are in
[`reference/rules.json`](/authoring/latest/extension/docs/extension-authoring/reference/rules.json).
In the installable bundle, load only the needed file under
`references/extension-authoring/`; runnable validation is under `scripts/` and
copyable examples are under `assets/examples/`. The offline routing snapshot is
`references/skill.json`; verify every resource listed in
`references/BUNDLE-MANIFEST.json` on installation or update. Reuse that verification while the bundle bytes are unchanged.

## Match the requested outcome

Use the relevant task mode, not the whole release lifecycle for every request.
A review produces findings; a repair changes and verifies the affected behavior;
a package request produces a validated artifact. Installation, publication, and
production rollout require those actions to be in scope. Continue authorized
independent work when a required host contract blocks only part of the task.

Read version-matched references once and reuse them while their version and
content remain unchanged. Inspect only the relevant surfaces and callers for a
bounded edit; a conversion or broad audit needs the fuller inventory. Do not
ask again for decisions or authorization already supplied for the same action.
Runtime permissions, exact confirmation tokens, and release evidence still apply.

## Select a task mode

Read the ordered `modes` entry in
[`skill.json`](/skill.json) before routing by surface. Supported
modes are create extension, convert application, audit/repair, add released
feature, complete product/UX without contract changes, prepare release,
upgrade/rollback, and operate live site (`CED-ROUTE-001`). The live-site mode
MUST route to
[Admin Site Operator](/skills/admin-site-operator.md) and MUST skip
this corpus unless an artifact or platform contract changes.

When offline, read the bundled `references/skill.json` instead of the public
URL. The bundled resolver returns exact local paths and MUST be preferred over
manually resolving relative links:
`node scripts/cedros-authoring.mjs resolve-path --repo <target> --mode <mode> --json`
(`CED-ROUTE-002`).

Audits, repairs, conversions, released-feature work, and upgrades MUST begin
with a repository inventory and preserve existing intent, stable IDs, migration
history, data ownership, and compliant architecture (`CED-AUTH-003`,
`CED-AUTH-007`).

## Source-of-truth boundary

- This guide and the [public skill index](/skill.md) are public and remain
  readable when the site itself is waitlisted, in maintenance, or otherwise
  gated.
- The complete version-matched contract is publicly browsable from the
  [extension authoring guide](/authoring/latest/extension/docs/extension-authoring/README.md).
  Its files are also available as a checksummed
  [extension authoring kit](/authoring/latest/extension/kit.zip).
  In a Cedros source checkout, the same guide starts at
  `docs/extension-authoring/README.md`.
- The authenticated MCP registry is authoritative for the tools, schemas,
  permissions, enabled extensions, and write modes available on the current
  site. Connect as described by [Admin Site Operator](/skills/admin-site-operator.md),
  inspect `resources/list`, then read
  `cedros://admin/areas/extensions/build-theme` or
  `cedros://admin/areas/extensions/lifecycle`.
- Never infer a manifest field, host import, permission, endpoint, or publish
  action from this summary. If it is absent from the downloaded kit and the
  authenticated registry, treat it as host-coordinated work.

## Official product boundaries

Standard customer-facing integrations do not configure static Cedros Login or
Cedros Pay service credentials. Use Login's `cedros-login:auth-response`,
host-supplied `cedros-login:user-context`, or public JWKS verification. Send the
end user's Login session to Pay's buyer-authenticated `/paywall/v1/*` routes;
Pay owns buyer verification through its Login integration. Generic shared-token
examples apply only when a consumer explicitly declares the specialized
service-to-service contract that requires one. Read `18` and `19` before
designing any Login or Pay integration.

For Balance, Compliance, or another official integration, load only its
version-matched contract from `18`, `19`, and their linked product guides.
Discover the installed provider's actual capabilities and grants; do not pin an
integration design to a version remembered from this overview. Preserve host
identity and permission checks, provider-owned routes, and the required
installed-host acceptance evidence for privileged or financial operations.

## Choose the correct product

Build an extension when the result adds behavior: server routes or jobs, admin
or public UI, blocks, data, providers, AI skills/capabilities, or integrations.
Use [theme authoring](/skills/cedros-theme-authoring.md) for presentation-only
changes. Use [custom page authoring](/skills/cedros-custom-page-authoring.md)
for site-owned page content assembled from registered blocks.

## End-to-end workflow

1. **Obtain the contract.** Read the public version-matched
   [guide](/authoring/latest/extension/docs/extension-authoring/README.md)
   and follow its links to the individual documents you need. Download the
   [kit](/authoring/latest/extension/kit.zip) when you need
   the runnable examples, validation scripts, WIT, or an offline copy, and
   verify its public
   [`AUTHORING-KIT.json`](/authoring/latest/extension/AUTHORING-KIT.json)
   and checksums. The host version serving these resources determines the
   supported contract.
2. **Plan the affected work.** Follow the selected mode's required and conditional references. Classify
   each requested surface as self-serve, metadata-first, host-coordinated, or
   out of scope. For a new extension or conversion, complete `03`'s host-seam decision record, including “not needed” entries. For a bounded change, update the existing record only where affected: managed intelligence/providers; host identity, login,
   authorization, and CSRF; structured logs, analytics, and durable audit/site
   brain; payments/entitlements; database/storage/settings/secrets/egress; and
   install/enable/disable/update/uninstall lifecycle. Record data ownership,
   dependencies, failure behavior, and every privileged seam.
3. **Start from the runnable floor.** For a new extension, copy
   `docs/extension-authoring/examples/minimal-extension` from the kit. Replace
   its demo identity consistently. Rename Cargo `[package].name` and keep
   `[lib].name` omitted (or align an explicit library name with the
   underscore-normalized manifest server entrypoint), regenerate the npm
   lockfile, and run `npm run sync:manifest`. Do not install an unpublished
   Cedros SDK from a package registry.
4. **Keep one canonical manifest.** `cedros-extension.manifest.json` is the
   source of truth. A schema-version-1 manifest declares the stable
   `extensionId`, package family, compatibility, surfaces, and requested
   capabilities. Generate `cedros-extension.bootstrap.json` and runtime
   projections from it; do not maintain divergent hand-written copies.
5. **Register only implemented surfaces.** The package family consists of the
   server, React, and React Native members described by `04`-`06`. IDs are
   namespaced and durable. Declared routes, jobs, modules, blocks, skills, and
   capabilities must match real compiled registrations exactly. Manifest
   metadata never executes by itself.
6. **Request least privilege.** Declare only the database, provider, settings,
   secret, CRM, egress, and other capability seams the implementation uses.
   The operator reviews grants and the host enforces them. Missing grants,
   dependencies, providers, settings, or host hooks must fail closed with a
   useful owner-facing state.
   Browser code must call an authenticated same-host extension route for
   privileged work; the Wasm route re-checks host-supplied identity and
   permission claims before calling granted imports. Never replace a site's
   managed intelligence provider, login identity, payment entitlement, audit
   trail, secret store, or storage seam with extension-owned credentials or a
   browser-local substitute without explicitly documenting why the feature is
   intentionally device-local.
7. **Implement lifecycle behavior.** Installation validates the archive;
   enable binds registrations and provisions documented seeds; disable stops
   active behavior without silently deleting owner data; update preserves
   compatible state and stable IDs; uninstall follows the operator's explicit
   data-retention choice. Migrations must be forward-safe and rollback must not
   pretend an irreversible data change was undone.
8. **Validate and test the artifact.** Run the copied project's documented
   install, manifest-sync, validation, build, package, and test commands as needed for the requested artifact. Reuse dependencies and passing checks for unchanged inputs; finalize formatting and lint fixes before the expensive final build.
   Exercise a happy path and meaningful denied/missing-dependency path for each
   privileged seam. Test browser/admin rendering, first-paint parity, wasm
   routes/jobs, enable/disable/update behavior, and accessibility where those
   surfaces are affected. If no Cedros runtime is available and the user authorizes sending the artifact to that service, submit the final ZIP
   through the [centralized Forge authoring scan](https://cedros.ai/extensions/cedros-forge/skill.md)
   for the profiles it actually advertises. A static result is preliminary
   package evidence, not reference-runtime, browser, or live-site evidence.
   The bundled deterministic verifier is `scripts/cedros-authoring.mjs`:
   `node scripts/cedros-authoring.mjs validate --repo . --json`. Its JSON rows
   use stable rule IDs and distinguish `pass`, `fail`, and `blocked`.
9. **Package the compiled result.** Follow `22`. The ZIP carries the canonical
   manifest and bootstrap at its root plus every declared compiled browser
   artifact and server wasm component. Validate the ZIP itself, not only the
   source tree. Record its checksum and never include credentials, local state,
   caches, or undeclared remote code.
10. **Prove compatibility and release readiness.** Follow `23` and `24`. Check
    schema/platform versions, the host-reported wasm/WIT contract when used,
    dependency minimums, upgrade and rollback behavior, and a clean install on
    a representative site. A successful local package is not evidence that a
    marketplace or production deployment is live.
11. **Publish deliberately.** Upload the private ZIP through the site's
    authenticated Extensions workflow, review requested grants, install it
    disabled when review is still pending, then enable and smoke test. Use the
    deployment's authenticated registry for current upload/install tools.
    Marketplace publication, signing, approval, promotion, and production
    rollout remain registry/operator workflows; follow the target host's
    current review and release process rather than inventing an endpoint.

## Guide map in the versioned kit

| Need | Read |
| --- | --- |
| Mental model and planning | `01-extension-system-overview.md`, `03-planning-an-extension.md` |
| Manifest, package family, runtime | `04-manifest-reference.md` through `07-wasm-server-backends.md` |
| Data, settings, providers, jobs | `08-site-database.md` through `11-jobs-and-scheduling.md` |
| Admin, pages, blocks, content, analytics, AI | `12-admin-pages-and-dashboard-cards.md` through `17-ai-skills-and-capabilities.md` |
| Product and relying-party contracts | `18-official-extension-integrations.md` through `21-host-coordination-and-native.md` |
| Package, version, release, example, fixes | `22-packaging-and-upload.md` through `25-troubleshooting-and-faq.md` |

For an AI skill or executable capability, `17` owns the manifest contract.
Public discovery may advertise it, but execution still uses the manifest-owned
endpoint and real host authorization. Do not copy a live input schema into
static documentation.

## Release evidence

A release packet should identify the manifest and package versions, host
compatibility, artifact checksum, validation/test commands and results,
requested grants, migration and rollback notes, install/enable smoke evidence,
known host handoffs, and publication status. Keep unavailable external evidence
visible; never convert a mock, stale example, or local check into a production
pass.

Only when evaluating the documentation system itself, use the checked-in `evals/*.jsonl`
fixtures and the bundled `evaluate-routing`, `evaluate-execution`, and
`compare-evals` commands. Responses are independently assessed observations,
not subject-agent self-reports. Match model, prompt, split, and repetition
count across with-skill and without-skill runs (`EVAL-ROUTING-001`,
`EVAL-EXECUTION-001`, `EVAL-COMPARISON-001`).

## Failure protocol

If a required reference cannot be fetched, version context is unknown,
same-precedence sources conflict, an SDK export is missing, repository state
contradicts the manifest, a capability is draft/planned, a host dependency
cannot be exercised, authentication fails, or a required user decision is unresolved,
MUST preserve safe completed work and stop the affected contract
(`CED-AUTH-005`). Continue work independent of that dependency and report unavailable runtime checks as unverified. Use the structured report when a contract blocker prevents the requested outcome; routine successful edits do not need a release packet. Return:

```json
{
  "status": "blocked",
  "blockingRule": "CED-AUTH-001",
  "reason": "Schema and SDK references disagree",
  "evidence": ["source and hash for each conflicting contract"],
  "workStillCompleted": ["safe work independent of the conflict"],
  "requiredResolution": "Cedros must publish the authoritative contract"
}
```

HTTP `401` means missing or invalid authentication. HTTP `403` means the
authenticated principal lacks scope; MUST NOT retry around it. Lack of local
testability is not success, and host-dependent behavior MUST NOT be reported as
verified without reference-runtime or live-site evidence (`CED-AUTH-004`,
`CED-AUTH-006`).