# Contributing

This is the home of the core, the runtime, the remote
and the SDK the twins (`@volter/twin-<vendor>`, in `volter-ai/twin-packs-p3`) run on. The repository is private, and nearly every change in it is made by an
agent working in its own git worktree under the process in [AGENTS.md](./AGENTS.md).

Two kinds of work, two processes. A **twin** is a package, `@volter/twin-<vendor>`, in `volter-ai/twin-packs-p3`,
created from its vendor's spec by one procedure, [Creating a pack](./docs/contributing/architecture.md#creating-a-pack),
with this repository's tools. **Platform** work, on core, the kernel, the SDK or the tools, records its intent in the
owning architecture section first. [Architecture](./docs/contributing/architecture.md) holds the rules;
[gates](./docs/contributing/gates.md) says how a change is verified and how to read a red;
[style](./docs/contributing/style.md) says how to write here. Bun 1.2+ and `bun install` at the root are the whole setup.

Do not include real API keys, tokens, private URLs or customer data in issues, artifacts or
transcripts.

## Publication

Every push to `main` runs [.github/workflows/publish.yml](.github/workflows/publish.yml).
Its [.github/autorelease.mjs](.github/autorelease.mjs) detects changed public package
directories and their exact-pinned or workspace consumers, increments their patch
versions, and updates the lockfile. The publisher builds and packs the versions
npm lacks, publishes those tarballs with the repository's `NPM_TOKEN`, then pushes
the version commit to `main`. Private apps are not npm packages.

There is no separate manual approval inside that workflow. An authorized push to
`main` therefore authorizes the configured publication; an owner-requested hold
must be resolved before that push. Publication credentials remain repository
secrets. Do not publish manually to duplicate this pipeline, overwrite immutable
versions, or report a running/failed/missing workflow as deployed.

Record the exact source SHA, successful workflow run and published versions.
The workflow's upload success does not prove registry availability or application
behavior: retain downloadable artifact identity and the promised workflow's
independent evidence. This publisher is a release job, not a CI merge/test gate;
the owner's verification instructions still govern tests and reviews.

Changesets retain version intent and the proposed major release train. That
manual train is distinct from the active patch publisher and is not evidence
that ordinary `main` pushes wait for another publication decision. The pipeline
does not consume changesets or enforce their fixed-platform version group.
[ADR 0013](docs/adr/0013-main-pushes-publish-through-the-existing-ci.md) records
this correction to the publication documentation.