Use this section to change an individual- or organization-operated Energon deployment repository 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 Energon 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 this Energon’s origins, policy, and SOP, 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 copy into private repositories and run. getenergon.com  explains the project; it does not host files or provide an Energon account. Issues and pull requests are welcome against tmchow/energon. Small focused patches that follow CONTRIBUTING.md  are the ones that land. Merge is not promised.

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, write passwords, customer content, or other people’s email addresses. A permissive Access policy or leaked token on one deployment is an deployment 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, hub /account, and dispatch into /v1. Content-origin /llms.txt is classified before the content-host catch-all 404.
2. src/v1-routes.ts and src/route-table.ts dispatch /v1 from auth-class tables (handshake none, bearer token, admin). A new /v1 row cannot omit the guard.
3. src/auth.ts and src/gate.ts establish human, token, and public-reader access. src/guest-write.ts authorizes tokenless PUT and site-path DELETE from X-Energon-Write-Password.
4. src/sites.ts and src/files.ts coordinate authenticated domain mutations across D1, R2, quota, and cache. Guest mutation stays in guest-write.ts and does not call those helpers as-is.
5. src/policy.ts, src/expire.ts, src/catalog.ts, src/handles.ts, src/urls.ts, and src/http.ts hold shared rules.
6. src/db.ts, src/schema.sql, and migrations/ describe the database at runtime, now, and through history.
7. templates/, instance-skill.json, and scripts/render-skill.mjs produce the installed agent plugin.
8. src/ui/pages/, src/ui/components/, and src/ui/design/ own presentation; src/page-data.ts, src/ui-render.ts, and scripts/build-ui.mjs connect it to Worker rendering and compiled assets.
9. test/, fuzz/, and .agents/skills/verify-energon/ prove behavior at increasingly realistic boundaries. The same .agents/skills/ tree also ships cut-release, update-from-upstream, and backup-this-energon. The Claude and Cursor skill paths are compatibility symlinks.

Before changing layout, styling, copy, or interactions, read upstream DESIGN.md  and the UI guide .

The router intentionally handles /health, /v1/health, /v1/help, /v1/openapi.json, /llms.txt, /auth.md, diagram renderer assets (/static/pele/*, /static/mermaid/*), 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, /auth.md, hub and content /llms.txt, and the installed skill are synchronized views of the same protocol. Guest-write copy is authored in src/guest-write-protocol.ts; changing it must fail CI if hub llms, content llms, help, or the rendered skill disagree. Content /llms.txt must not mention /v1, /auth.md, /keys, or /connect. 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 or guest-write behavior changes, review these semantically instead of assuming separate automated checks prove they say the same thing.

User-facing handles stay testable

Page tests protect server-rendered structure, hydration, navigation, and asset isolation; Svelte checks template bindings. The verify harness proves human and agent workflows against a real local Worker, D1, and R2. Neither substitutes for the other: browser and HTTP drives check behavior across the actual user path, including conditional forms and dialogs.

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.