Keep your kits right after a release

A kit is a versioned selection of the project's assets that an agent is given for one kind of work. It is not an asset: it never appears in the changeset, a release never changes it, and it can hold only assets that already exist. So a client that uses only the API publishes first and writes the kits afterwards.

The Context Repository is self-contained. Nothing here depends on Continual Learning. A kit has an auto_maintain setting (off by default) reserved for automatic upkeep of its members by Continual Learning, which never creates or deletes a kit. That upkeep is planned and not available today: nothing reads the setting yet. Until it exists, and for any project that does not run Continual Learning, the client keeps its kits right. Gaps behave the same way: a gap stays open until a person or the client retires it with a delete_asset op in a later changeset.

Every kit write needs the context:kits scope. Reading a kit or its journal needs context:read.

The first time: assets, then kits

1. Stage the assets with Stage ops: pages, entities, skills, pointers, gaps and their links. Stage no kit; there is no kit op.
2. Have the changes reviewed and published (Merge the change request). A staged asset does not exist for a kit until it is published, and naming one is refused with 422 reference_not_found.
3. Take the ids from the service. An asset keeps the id it was given when staged; Search the project's context or List assets returns the published asset with its id.
4. Create the kit with Create a kit, naming its members by id. Leave role out: the asset's type decides how the kit holds it (most types are contained, a tool is offered, a gap is carried). Give the kit a description that names the situations it serves, in the words a first request would use, because a session picks its kit by ranking the first message against those descriptions.
5. Read the kit back with Get a kit and check that every need it exists for is answered.

Every later release

A release changes assets and leaves every kit exactly as it was. Serving skips a member the release retired and follows its recorded successor, but the kit still names the old asset until you repair it. After each release that adds, retires or supersedes assets:

1. List kits and get each one. Its ignored_members lists every member the release could not serve, with a reason: retired (nothing replaced it), superseded (a successor is served in its place and named in successor_ids) or unpublished (the release you pinned does not hold it yet).
2. For a superseded member, add the successor if the kit does not hold it, then remove the old member.
3. For a retired member, remove it, and record a gap if the need it served is now unanswered.
4. For a new asset, add it to the kits whose purpose it serves.

Concurrent edits

Every kit write except create names the kit version you read as base_version. If the kit has moved since, nothing is written and the answer is 409 kit_moved. Read the kit again, recompute your change against what is there now, and send it with the new version. Never resend the same body unchanged, and never overwrite a person's change.

Reading a retired kit without version returns 404 kit_not_found; its stored versions remain readable with ?version=N. Each change appends a version and a line to the kit's journal, and reverting to an earlier version is one write.