changes

Files (1)

• SKILL.md

SKILL.md (first lines)

# Changing a tenant that already exists

A tenant is not generated once. It adopts blueprints, grows components, and is
rebuilt. Creating one is `tenants`; this skill is everything after that.

Rules, names and tables live in
`architecture/generation.md`. This skill says
which verb to run and which section to read.

## Add a component

```
weblisk component help                   # what this installation can build
weblisk component <kind> init [--platform go]
```

**An orchestrator is a tenant's first component, not the tenant.** A tenant is
a set of siblings in one module, each registering with the orchestrator on
start. `architecture/orchestrator.md`, "What a tenant consists of", gives the set
two homes: what a tenant is running is `GET /v1/services`, and what it should
build and start is `.weblisk/config.yaml`. Ask the first when reporting; the
second is an intention, and a declared component may not be running.

Buildable kinds come from this installation's blueprints; the command lists
them when the name is wrong. A tenant's second component is where the
interesting failures live — the planner must be told about the tenant, not just
the blueprints, or it plans a fresh module over an existing one.

`--resume` continues a run that died on a provider limit. Only `server init`
and `component <kind> init` are resumable; do not suggest it for other verbs.

### Check the listed kind has a blueprint to generate from

`component help` lists a kind when its architecture blueprint states an
`## Endpoints` table and declares bindings. Whether the pipeline then *reads*
that blueprint is a second question, and the two sets are not the same.

Before running `component <kind> init` for a kind you have not built before,
run it and read the announced blueprint list. **If the component's own
blueprint is not in it, stop.** The run will otherwise plan from the protocol
and the platform alone, produce a plausible file set, and pass its own checks —
a component generated against nothing, reported as generated.

### Content

`weblisk component content init` builds the tenant's content service —
the thing that lets a tenant hold authored text rather than only run code.
What it serves, what custody means, and what declaring a repository requires
are all `architecture/content.md`; none of it is repeated here.

Two things about it are operational rather than specified, and are what an
agent gets wrong:

- **Generating it is not the end.** A content service with no repository
  declared holds nothing, and a tenant that has one must still be told which
  stores it governs.
- **Nor is it running.** `weblisk component content start --detach` runs it
  against the tenant's orchestrator. Declaring `content:` in
  `.weblisk/config.yaml` makes `weblisk server start` run it with the rest,
  and `weblisk server stop` stops it with them.
- **The first adoption call is meant to fail.** Adopting a store that already
  holds bytes is two calls: the first returns a census and refuses, the second
  passes that census digest back as `if_match`. Treat the first refusal as the
  answer, not as an error to retry or work around — see `architecture/content.md`,
  "Declaring a Repository".

## A programme names what to build

Adopting a programme answers a **build plan**: the services it needs that the
tenant does not run, each with its blueprint, in build order.
`schemas/programme.md`, "What a programme runs on", is the one home of which
service each block needs, the name each registers under and the order; do not
keep a list of your own.

- Build each from its own blueprint, in that order. A service marked
  `adoption: opt-in` — the fabric — is never pulled in as another's
  dependency, so name it when the plan does.
- The specified way is a change: `weblisk change plan --adopt <ref>`,
  approved by a person, then `change apply` in the tenant
  (`architecture/cli.md`, "Changes"). Where this CLI does not build `change`
  yet, `component <kind> init` is how a service is added.
- A programme is not running because it was adopted. Only an empty plan says
  the tenant runs everything the programme needs.

## Decide before you build

The rebuild decision is **per file**, and the default answer is KEEP.
`architecture/generation.md`, "Deciding whether a file must be rebuilt",
declares the conditions; first match wins.

Two of them are **refusals, not instructions**:

- a file that differs from what generation wrote
- a file generation cannot show it wrote

Neither regenerates. They are reported apart because the remedy differs: one
sends somebody looking for their own edit, the other is what is true after a
manifest is lost or a run was interrupted before recording.

**Never treat a refusal as "rebuild".** Doing so overwrites the edit the verdict
exists to protect.

A blueprint change does not regenerate a component. It is assessed against each
file, and a file the change does not reach is left alone. One digest over the
whole prompt cannot make that distinction — it answers "did anything change" and
never "did anything I depend on change".

### Has upstream moved since it was built?

```
weblisk build status --upstream [--json]
```

Run it before deciding. It compares every blueprint the build recorded — path,
sha256, declared version — with the corpus a rebuild would read now, by
`schemas/programme.md` §Versioning's table, and compares the recorded set with
the graph a rebuild resolves. It changes nothing.

- **`unmaintained` is not `changed`.** The bytes moved and the version did not:

From avaropoint/weblisk-blueprints, MIT.

More from avaropoint/weblisk-blueprints