Use this section to change an individual- or organization-operated Energon fork or complete an owner-requested upstream patch without breaking the publishing contract. A route or schema edit may also affect D1 metadata, R2 bytes, the OpenAPI schema, runtime help, the generated plugin, and user-path verification. Trace those representations first because the final change must not strand an older instance or teach agents behavior the Worker lacks.

Contribute to Energon

One change can cross several contracts

Energon is a compact Cloudflare Worker, but its correctness is distributed. D1 records identities, policy, catalog metadata, claims, and quota. R2 holds the published bytes. OpenAPI defines the HTTP schema, runtime help describes instance identity and policy, the generated plugin turns the protocol into a workflow, and the hub exposes the same domain operations to people.

A change is complete only when every affected representation agrees. The glossary defines the project-specific terms used for identities, policies, and mutation coordination:

This is why the repository treats schema shape, mutation rollback, generated instructions, and verification recipes as code contracts rather than optional cleanup.

Pick the contribution lane

The upstream repository is source that individuals and organizations fork and run. getenergon.com  explains the project; it does not host files or provide an Energon account. The upstream repository does not accept unsolicited patches.

Fork-origin pull requests to tmchow/energon are closed automatically. Do not open an upstream pull request unless the owner asked for that patch. On an operator fork, follow that repository’s maintainers and review policy.

Private security reports should include the tested commit or release, reproduction steps, and attacker impact. Never include live Energon tokens, Cloudflare credentials, Access JWTs, share passwords, customer content, or other people’s email addresses. A permissive Access policy or leaked token on one deployment is an instance incident unless the source code itself caused it.

Read the system in layers

The shortest useful tour follows a request from the edge inward:

1. src/index.ts owns host separation, early discovery routes, schema bootstrap, and dispatch.
2. src/auth.ts and src/gate.ts establish human, token, and public-reader access.
3. src/sites.ts and src/files.ts coordinate domain mutations across D1, R2, quota, and cache.
4. src/policy.ts, src/expire.ts, src/catalog.ts, src/handles.ts, src/urls.ts, and src/http.ts hold shared rules.
5. src/db.ts, src/schema.sql, and migrations/ describe the database at runtime, now, and through history.
6. templates/, instance-skill.json, and scripts/render-skill.mjs produce the installed agent plugin.
7. test/, fuzz/, and .cursor/skills/verify-energon/ prove behavior at increasingly realistic boundaries.

The router intentionally handles /health, /v1/health, /v1/help, /v1/openapi.json, /llms.txt, Mermaid assets, and the content-host boundary before the normal schema-backed dispatch. Scheduled execution bootstraps schema and then sweeps expired content.

Four contracts to preserve

Storage and catalog converge

A site file or loose file exists as both catalog metadata and R2 bytes. Writes reserve quota, snapshot or stage prior bytes, commit catalog state conditionally, and compensate after failure. A rollback failure becomes an explicit recovery error; it is never silently reported as success.

Old databases still start

Schema changes update three places: a new append-only migration, runtime bootstrap and legacy upgrade logic in src/db.ts, and the current documented shape in src/schema.sql. Columns must exist before indexes. The supported historical 0005 shape must still reach a usable current schema without rebuilding persisted identity relationships.

API and agent views stay synchronized

openapi/v1.json, /v1/help, /llms.txt, and the installed skill are four synchronized views of the same protocol. test/unit/openapi-drift.spec.ts ties the HTTP schema to router operations, help routes, and application error codes; golden tests freeze the runtime documents, while render tests freeze generated skill output. When /v1 behavior changes, review all four semantically instead of assuming separate automated checks prove they say the same thing.

User-facing handles stay testable

Page tests protect HTML structure and JavaScript element bindings. The verify harness proves the human and agent workflows against a real local Worker, D1, and R2. Neither substitutes for the other: contract tests catch missing ids cheaply, while browser and HTTP drives catch behavior across the actual user path.

Start a local change

The basic repository loop is intentionally small. It uses local migrations and a development identity; it does not touch production.

npm install
npx wrangler d1 migrations apply energon --local
cp .dev.vars.example .dev.vars
npm run dev

The default development server is http://127.0.0.1:8787. Localhost skips Access, and the default identity is dev@example.com. Keep verification runs off this server: the isolated verify harness uses port 18787 and its own /tmp persistence by default.

Decide what proof the change needs

Start with the narrowest test that owns the behavior, then widen when the change crosses a contract boundary:

• Pure helper changes use the matching Node unit test.
• Routes and page bindings use their focused Worker suites.
• Publish behavior uses API tests; mutation changes also use failure-injection and mock-free D1/R2 suites.
• /v1 contract changes include the OpenAPI drift test, golden runtime docs, template/render review, and relevant user-path recipes.
• Schema and shared-type changes run the full generated-types, typecheck, lint, and test gate.

npm run test:unit -- test/unit/catalog.spec.ts
npx vitest run test/api.spec.ts

CI repeats the complete validation sequence, including ZIP fuzz regression. The focused loop is for fast feedback, not permission to omit broader proof before handoff.

Next steps

• Architecture and integrity explains router boundaries, D1/R2 mutation convergence, claims, schema evolution, and generated artifacts.
• Develop and verify maps change types to tests, CI, fuzzing, semantic documentation review, and the isolated user-path harness.
• HTTP API is the runtime contract contributor-facing route changes must preserve.
• Upgrade and recover covers the human operator’s migration and recovery procedure.