# Sidecat development guide

**Guide for accepted product revision 3 and development revision 2 · 29 September 2026**

This guide accompanies the [product contract, revision 3](https://sidecat.dev/development/version-1.html)
and [development agreement, revision 2](https://sidecat.dev/development/process.html),
approved together on 29 September 2026. The guide maintains evolving role groupings,
specializations, reading paths and practices. It can change within delegated work,
but cannot waive, amend or grant authority under either agreement.

The role map is a working arrangement, not live assignments or proof of qualified
native activation. Exact assignments, plans, decisions and evidence belong in Sidecat;
[progress](https://sidecat.dev/development/progress.html) reports changing facts.

## Current role map

A Sidecat Role is reusable responsibility. A Sidecat Actor has a durable identity
independent of its assignments and may hold several roles; several actors may hold
one role. Role packaging can change with workload and organizational needs while
preserving the development agreement's accountability coverage and independent input/review.

The following component and product-wide groupings are working starting points.
They are not an exhaustive roster or a requirement for permanent model processes.
Name actual owners, exact role revisions and selected scope on the current
assignment; do not infer live assignments from these tables.

### Component roles

| Sidecat role | Primary responsibility | Boundary it must protect |
| --- | --- | --- |
| Node and bus | Registry, local dispatch, supervision, event/subscription contracts and bounded delivery | Does not absorb domain records or run domain-specific SQL. A new app uses registration instead of daemon surgery. |
| Federation | Peer identity/addressing, remote calls, delivery/recovery and independent administration | A remote call retains its operation meaning and authority; connectivity does not confer access. |
| Authorization and resources (`sidecat-auth`) | AAuth integration, policy/approval decisions, delegation, budget reservation and reconciliation | Resources have a named authority/accounting owner. No invented authority or spend during a partition. Consume the standalone AAuth library through its public interface. |
| AAuth Go (`aauth-go`) | Independently maintain the general Go implementation: refresh specification references, assess conformance, guide and implement justified updates | Keep the library useful outside Sidecat. Sidecat-specific policy, branding and integration remain outside its repository. |
| Execution | Prepared environments, commands, adapters, outputs, cancellation and unknown-effect reconciliation | Orchestration asks for execution; the executor reports what actually happened. No duplicate consequential effect after a lost reply. |
| Orchestration | Typed routines/subroutines, durable workflow state and replaceable harness execution | Procedure semantics survive agent/daemon replacement. It does not own Work's meaning or infer success from fluent text. |
| Content and records | Note/content revisions, names, blob references, source links and retrieval | Exact historical content and access are explicit. Does not become the universal business-object or workflow database. |
| Work and planning | Work definitions, Plan occurrences, contextual backlog/board/facet use and multi-project continuity | Work is reusable; occurrence completion stays contextual. Multiple projects do not become competing copies of one work description. |
| Organization | Organizational structure, purpose, principles, portfolios and working context | A statement, adopted policy and effective grant are distinguishable. Domain facts do not themselves grant authority. |
| Roles and actors | Reusable role definitions, named actors, role assignments and activation requirements, composed with existing identity/assignment/execution owners | An actor persists across runs; its selected model is not its business identity. Do not duplicate task queues, credentials or run storage. |
| Messaging | Collective rooms/direct messages, threads, structured references, catch-up and attention | Durable conversation remains useful through turnover, backlog and scope changes. No Work creation merely to send a message. |
| Lisp and composition | Language profile, resident sessions, retained methods and partial execution | One documented language meaning. Interpreters/helpers do not multiply silently or bypass operation authority. |
| Marketplace and packages | Public and self-operated internal marketplace publishing, access, discovery, inspection, distribution and package lifecycle; common vocabulary/shape discovery | Go/Lisp/workflow/role/resource and mixed packages extend ordinary interfaces. Installing roles assigns no actors, grants no permissions and launches no workers. Semantics aid authors without importing domains into core; split stewardship when sustained work warrants it. |
| Sidecat UI (`sidecatui`) | Open-source operator client: goals/work/roles, conversation, decisions and honest resource visibility | Consume shared Sidecat records and authority. No private competing work state or approvals inferred from chat. Qualify keyboard use, narrow terminals and lead-unavailable operation. |
| Clients and connectors | CLI/MCP projections and external-service adapters | Shared meanings, clear help, structured references and usable errors. Connector-specific behavior remains behind its declared interface. |

An actor holding a component role maintains its contract, local tests and
documentation as well as features. A concern outside the assignment goes to its
owner or product management. Expanding a component's private ownership requires
boundary review, even when its current role groupings change.

### Product-wide roles

| Sidecat role | Accountability | Required contribution |
| --- | --- | --- |
| Product manager | Product purpose, scope, acceptance and coverage across component boundaries | Trace each selected outcome to product purpose, applicable requirements and real use; identify missing ownership, duplicate features, orphan work and software-only assumptions; maintain a concise whole-product readiness view. Propose changes to required scope to the operator. |
| Scrum lead / delivery manager | A coherent sprint, dependencies, capacity and visible progress | Gather independent input, select ready assignments with owners, coordinate integration and resolve blockers. Keep new ideas in refinement until deliberately selected. Do not silently change the target or redirect every actor mid-sprint. |
| Systems integration reviewer | Common contracts and the behavior of parts together | Review boundary changes, shared-library growth, database ownership and multi-node composition. Require a focused consumer proof for changed shared contracts. It does not become the author of all components. |
| Call surface and agent usability | Prevent recurring task-discovery, prerequisite, sequencing and recovery failures across applications | Use the [call-surface role guidance](https://sidecat.dev/development/call-surface.html), relevant existing decisions and installed task evidence. Large official, third-party and local catalogs are expected; assess usability, not their size. |
| QA lead | Quality of the installed product and the evidence for it | Design exploratory, adversarial, concurrency, recovery and unfamiliar-user trials; assess every affected help/man/example path, documentation, code readability and unnecessary tests. Distinguish observed results from participant claims. |
| Release engineer | Exact candidate, packaging, distribution and controlled activation | Produce/reproduce the selected artifact, check evidence matches it, verify installer/publication/rollback, and publish its actual capabilities and limits. Does not decide product scope or waive QA findings alone. |

These roles cover the development agreement's required product, delivery, integration, QA and
release functions. One actor can hold several roles, but the implementer cannot be
the only reviewer of a consequential change or the only observer qualifying the
installed result. The development agreement determines the required coverage and independence;
this table describes one way to organize it.

### Specializations and working arrangements

A team can group roles, divide a broad role into narrower responsibilities or use
subroles for a selected workload. For example, a clients and connectors role might
use a specialist for one connector, or QA might distinguish recovery and newcomer
trials. These are organizational choices, not a required role-inheritance system.
Each selected role states its own scope, obligations, outputs and escalation;
shared obligations are referenced explicitly and grants remain separately authorized.

Record the actors holding each selected responsibility and the component and
review boundaries before work relies on the arrangement. A refinement of role
packaging cannot drop accountability, replace independent input with one lead's
answer or make several actors unknowingly edit the same working tree. Qualified
execution implementations can change without changing the role's identity.

## Product purpose and source-backed views

Version 1 design follow-up requested on 29 September 2026, developing V1-01,
V1-02, V1-03, V1-10 and V1-14. The product contract requires product/project
context and source references; detailed object and operation contracts still
need design and consumer review. These are proposed boundaries, not installed
Product/Principle operations or a new approved wire schema.

Purpose, north stars, goals, principles and working guidance are existing core
product concerns, not a new optional feature family. The existing call/object
surface informs their replacement. A focused check on 29 September found:

| Existing capability | Observed basis | Carry-forward question |
| --- | --- | --- |
| Organization baseline | Installed create/current operations expose direction, principles, constraints, operator statement and separate agent interpretation. | Preserve these meanings and original-versus-interpreted distinctions through the new owner/content boundaries. |
| Working guidance and references | Existing revisioned guidance and named references retain text, purpose, source, status and reader scope. | Reuse exact content and access behavior; remove duplicate authoritative text paths. |
| Project context | Existing Project metadata, Work links, planning and progress records. | Separate durable product scope from project effort without losing existing coordination functionality. |
| Profile, Goal, Practice and Contribution | In-progress local organization-package source and behavior-test definitions; not present in the selected live catalog or qualified by this inspection. | Review with the current owner before designing overlapping objects; carry useful outcomes forward and qualify the installed replacement. |

The existing Gen5 coverage analysis and modularization plan already require this
capability mapping. For each selected area, compare intended, implemented and
verified behavior; name the new owner and choose reuse, extraction, revision,
rebuild or retirement with reasons and acceptance evidence. Search beyond operation
names. Do not silently drop a capability because it is absent from a fresh node,
and do not preserve a call merely because it exists. The proposed distinctions below
must be checked against that source and current owners before implementation.

| Concept | Proposed responsibility |
| --- | --- |
| Product | Lasting purpose, intended users, scope and desired outcomes, with references to applicable principles and product commitments. Products need not be software. |
| Project | A coordinated effort toward an outcome, linked to the products or organizational goals it serves. Several projects can serve a product; a project can serve several products. |
| Principle | A revisioned statement with rationale and content references. Explicit scoped adoption connects it to an organization, product or project. A principle does not itself become policy, permission or an execution gate. |
| Work and Plan | Reusable Work describes the task/outcome; Plan occurrences carry assignments, sequence, dates and judgments. They refer to relevant product/project context instead of copying it. |

The open-source Sidecat product and a commercial offering can share referenced
principles while having different scope and delivery commitments. Organizational
structure and policies remain separate from product/project meaning. Resolve
applicability and conflicts explicitly; membership or a reference alone does not
create automatic inheritance, priority or permission. Component/database grouping
is still an implementation decision under the common app contract.

### Local definitions, packages and task surfaces

Apply the product contract's [fundamentals](https://sidecat.dev/development/version-1.html#fundamentals-and-user-facing-composition)
when choosing how to expose a capability. A user's "north star" can be a named,
typed entry under product context, with meaning and applicability defined locally
or by a package. It need not become another mandatory core object/verb. Supported
owners provide record creation, revisions, queries and relations; domain operations
and routines remain discoverable and usable through the common surfaces.

Start with the relevant existing capability, then decide whether to reuse a
definition, extend a supported shape, compose a routine or add Go behavior.
Workload, invariants and total development cost guide that choice. Go applications
can own substantial domain logic; infrequently changed definitions and composition
can live in Lisp/data. A technical rule against Lisp owning storage must not silently
exclude package-defined persistent records through a storage owner's interfaces.
Affected owners review the exact extension contract before implementation relies on it.

A publishing routine can be selected for a project, prepare artifacts and call
Git or other effect owners. Its definition, inputs, authority and continuation are
inspectable. Hiding required checks in CLI-only wrappers would defeat this design.
Package-specific procedures, editorial policies and styles remain optional choices.

The [captured discussion](https://gitlab.com/sidecat-dev/sidecat/-/blob/a7f60a4cd328c0991672b8544676888d83b13a3e/architecture/proposals/package-defined-working-environments-20260929.md)
uses Boxlab/FPRD as an adopter example: local practices become reusable packages;
records can produce a working directory or publication, and selected return
mappings can ingest outside work. Its detailed record shapes and procedures remain
proposals. The contract's bounded extension qualification does not require shipping
the complete research lab, an automatic bidirectional synchronizer or an air-gapped
execution product. The full file/Git return journey remains a candidate package
trial under that proposal, not a new mandatory Version 1 acceptance path.

### Published views and working context

Build toward readable pages and bounded agent context drawn from the same authorized
records. A publication view selects exact object/content revisions and maps fields
and relationships to displayed headings, text and links. Namespaced labels can serve
as anchors without appearing in ordinary prose. Human and agent views can differ;
derived summaries and omissions remain identifiable.

Deterministic QA compares the actual presented text and structure with the selected
sources: missing/duplicate records, incorrect grouping, changed text and broken
references are observable failures. A retained snapshot can be correct even when a
newer revision exists. A stamp or matching printed digest alone is insufficient.
Unavailable source material produces an explicit inability to verify. Access rules
still apply, and publication selects public material rather than exposing a store.
For execution, distinguish available records, delivered context and observed effects;
a saved packet does not prove understanding or compliance. The current purpose page
renders one Markdown source; that representation does not qualify these native features.

### Evidence-linked justification

Where a selected policy/workflow requires justification, retain the proposed action,
the agent's declared justification and exact supporting references before dispatch.
A Work description can lead through its originating Message to the user's exact Note
revision. Preserve the difference between original instruction and interpretation;
a valid source link alone is not approval for the proposed action.

Evidence coverage is separate from source accuracy. Resolve the applicable recorded
instructions, policies, amendments and known conflicts from the work/resource context,
not solely from evidence picked by the applicant. Review can request further context;
no claim that every relevant fact or hidden model motive is known. Changes to action,
artifact or applicable authority require the selected workflow's reassessment. This
is configurable assurance, not a mandatory historical audit on ordinary operations.

Qualification should demonstrate a linked product/project/principle, source-backed
publication with a deliberately detected mismatch, context delivery with exact source
references, and a selected justification review that finds an applicable contradictory
instruction despite accurate supporting citations. Fix the evidence and allow an
ordinary justified action; stronger assurance remains optional. Preserve these as
owned refinement work for later selection; do not redirect the active application
qualification cycle merely to implement this discussion.

## Development tools and packages

### Choose an internal utility or a prepared user task

Use the simplest maintainable home for the actual caller and task. Maintained
Node, Python, shell and Go utilities are useful for development and testing;
they can call Sidecat where needed. Moving ad-hoc coordination from Python to
Node does not itself fix procedure discovery, targeting or call sequencing.

Ordinary users, including agents using smaller models, should receive a prepared
task, its data and exact references. They should not reconstruct owners, IDs,
request keys and call sequences to do ordinary work. Writing reviewed methods,
routines or extensions is author work. Choose a clear task interface and usable
recovery; this guidance does not require every tool to be written in Lisp or
integrated into the Sidecat runtime.

### Packages and usage documentation

`sidecat-development-utils` should ship as a Sidecat package. Following the
Debian-inspired package model, packages can deliver end-user, development and
testing tools, documentation, resources and mixed content. A package need not
be an application, register on the bus or require full runtime integration.
Declare its contents and dependencies, with instructions for the actual caller.
Version and distribute maintained utilities rather than repeatedly creating
equivalent coordination glue.

Usage documentation and how-to instructions must be discoverable in Sidecat,
including for tools that operate only on files, repositories or external
services. Keep a named, source-linked reference to the maintained documentation;
do not maintain a second manual body for native readers.

### Current implementation gap and the `agt` example

As of 1 October 2026, the portable package format lacks plain-file/resource
delivery and installation of a reusable REPL library. This
is an implementation gap against [V1-07](https://sidecat.dev/development/version-1.html#v1-07),
not a new accepted requirement or proof that these packages already install.

`agt` should likewise be independently versioned and distributed, preserving
local configuration and login state. The current development installation is
a Bash launcher at `~/.local/bin/agt`; its canonical source pointer and package
delivery remain unestablished. This example identifies packaging work, without
requiring a launcher rewrite or changes to active sessions.

## Sidecat UI development direction

`sidecatui` is the new open-source operator-client project and product name.
Start from its required user tasks and selectively port useful Rust terminal
interface code and supporting functionality. Review each dependency and test its
public behavior; do not carry over an entire command surface or compatibility
structure solely because it already exists. A gateway still needed by the client
must be replaced, extracted or deliberately retained before its old implementation
is retired. This is a planned development cycle, not a claim that the new project
has been created or qualified.

The client uses shared Sidecat state for work, messages, roles and decisions.
Its marketplace view shows package source and distribution visibility separately
from experimental/testing/stable track. Bundled, organization-internal and connected
marketplaces are possible source examples, not fixed organization role types.
An internal package can be stable; a public package can be experimental. Inspect
content/dependencies and access before installation, then distinguish installation,
admission, activation and separately authorized role assignment.
Start the client in an early selected development cycle. Build its operator-facing
views alongside their owning application interfaces, then exercise both on the
same installed candidate during QA. Use the client for internal work before cutover.
The first useful view can open a project or an isolated test workspace: show its
purpose, recent work, active assignments, current tests and observed results.
Keep it open during a test to inspect the changes Sidecat actually records. Show
the selected environment, source candidate and freshness, including stale/error
states. This makes the client a consumer test of the shared interfaces, not a
private summary maintained by the lead.
Early priorities are operator orientation, communication without a working lead,
authorized responses and visibility into model/service availability, reported API
credits and prepaid allowance. Use ordinary Sidecat calls for usage and availability: include observation and
reset times where supplied, preserve actual worker/model and task attribution,
and keep provider-reported allowance, token counters and cost estimates separate.
Show observed, estimated, stale and unknown usage explicitly. A missing provider
field is not zero, and a reported cost need not be an invoice amount. Detailed analytics, alternate-plan
comparison and screen arrangements belong in the evolving roadmap. The initial
implementation is a Rust terminal interface; the contract specifies its useful
outcomes rather than a particular screen layout.

### Summary-first presentation

Prefer an existing title or summary field when the object already provides one.
For free-form notes and messages, use a short, understandable first line or opening
paragraph followed by details and structured references. Think of a useful
commit subject followed by its explanation. This is a writing and presentation
convention, not a new universal parser or object schema.

Sidecat UI can show the summary first and let an operator expand the full content.
An agent can obtain the structured details and references through the same owning
application. Refusals, uncertainty, blockers and requests for decisions must remain
visible in the concise view. Preserve the original content; do not maintain
competing human and agent bodies just to achieve a different layout. Test whether
the summary helps an unfamiliar operator understand what happened and what needs
their attention.

Design for the available terminal width and height. Put status and the next action
before supporting detail; keep uncertainty visible. Test narrow terminals and
keyboard access with real content. Richer reports can use a web view of the same
sources. The terminal client does not need to display every detail on one screen.

## Start with the assignment

Before a development cycle, identify:

| Reference | What it tells the actor |
| --- | --- |
| Product/development revisions and digests | Which jointly approved agreements govern the work |
| Actor and selected role-assignment references | Who is responsible and which role revisions apply |
| Work/Plan and current shared state | The outcome, owner, candidate, workspace, budget, stop conditions and next decision |
| Requirement IDs and applicable design rules | What this outcome must satisfy and the boundaries it must preserve |
| Current development checkpoint | Which evidence and accountable roles are needed before proceeding |
| Component contract and actual consumers | The public behavior other applications rely on |

An actor can read a relevant section, an exact captured excerpt, or a prepared
context packet. A packet states the source agreement digests and included section
anchors, requirement IDs and named table rows. A handoff preserves those
references and names any still-needed material. An excerpt is never described as
a whole agreement when it is only a selection.

## The common reading set

Every selected cycle needs the following information. It can be supplied as
bounded excerpts; unrelated components and historical research need not be loaded.

1. Product [purpose](https://sidecat.dev/development/version-1.html#what-we-are-building),
   selected [requirements](https://sidecat.dev/development/version-1.html#version-1-requirements)
   and [design decisions](https://sidecat.dev/development/version-1.html#agreed-design-decisions).
2. Product [roles/actors/runs](https://sidecat.dev/development/version-1.html#roles-actors-and-runs),
   selected role definitions, assignment scope and effective authority.
3. Development [accountability](https://sidecat.dev/development/process.html#required-roles-and-accountability),
   applicable [cycle](https://sidecat.dev/development/process.html#development-cycle) and
   [checkpoint](https://sidecat.dev/development/process.html#firm-checkpoints), including
   independent input, review and installed observation.
4. Relevant development [risks](https://sidecat.dev/development/process.html#risks-that-can-defeat-this-effort),
   [context/amendment rules](https://sidecat.dev/development/process.html#context-amendments-and-manual-checks)
   and used component/dependency contracts.
5. For capacity, release, publication or cutover, product
   [shipping/scale constraints](https://sidecat.dev/development/version-1.html#shipping-capacity-and-extensions)
   and development [cutover qualification](https://sidecat.dev/development/process.html#internal-clients-and-cutover-qualification).

These readings include the 25,000-agent target, initial 500-caller qualification,
explicit lower-scope decision, and distinct internal-catfood/preview/full-release claims
when relevant. Select the necessary paragraphs, not the whole history.

The assigning owner selects applicable material and checks the selection for
missing obligations. An actor reports a material gap when its assignment cannot
be checked from what was supplied. This is targeted orientation, not a requirement
to summarize every section or repeatedly load the full document.

## Reading by role

These paths can evolve as the role map changes. They are starting points. An
assignment that crosses a boundary also needs the affected component's contract
and its consumer's requirements.

| Sidecat Role | Read in addition to the common set | Decision it contributes |
| --- | --- | --- |
| Product manager | Full product requirements, design and [shipping/scope](https://sidecat.dev/development/version-1.html#shipping-capacity-and-extensions); development accountability, risks and cutover rules; selected role definition | Does the outcome serve the product, cover its requirements and preserve the agreed scope? |
| Scrum lead / delivery manager | Development [cycle](https://sidecat.dev/development/process.html#development-cycle) and checkpoints; participating component roles; current assignments, capacity, dependencies and continuation | Is one coherent outcome ready with owners, review coverage, budget and stop conditions? |
| Systems integration reviewer | Product interface, ownership, storage, federation and composition rules; development [dependency decisions](https://sidecat.dev/development/process.html#shared-contracts-and-dependency-decisions); affected component contracts and consumer evidence | Can independently developed parts rely on the change without hidden coupling or conflicting meaning? |
| Component maintainer | Its component-role row and requirement IDs; used dependency contracts; development [surface/testing discipline](https://sidecat.dev/development/process.html#surfaces-documentation-and-testing) and checkpoints | What must this component own, expose, test and remove? |
| QA lead | Development surface/testing discipline, [assessment checks](https://sidecat.dev/development/process.html#context-amendments-and-manual-checks), independence, risks and current acceptance; product shipping/scale when relevant; affected docs | What does the installed candidate prove, what failed and what remains unqualified? |
| Release engineer | Product installation/distribution/execution requirements and shipping/scale; development release/publication checkpoints; artifact/configuration, installer/recovery/rollback and [cutover](https://sidecat.dev/development/process.html#internal-clients-and-cutover-qualification) | Is the artifact reproducible and qualified for this destination and scope? |
| Roles and actors maintainer | V1-10 and product native lifecycle/context; development assignment context and launch/cutover qualification; Work/Plan, Messaging, orchestration, execution and auth contracts | Are roles reusable, actors addressable offline and actual runs attributable without duplicate identity or queues? |
| Marketplace and packages maintainer | V1-07 and [package lifecycle](https://sidecat.dev/development/version-1.html#marketplace-and-packages); public/internal hosting/access, Go/Lisp/workflow/role content; dependency decisions and independent author/consumer trials | Can authors deliver and organizations operate their own marketplace without implicit actor assignment, trust or authority? |
| Sidecat UI maintainer | V1-16 and [operator outcomes](https://sidecat.dev/development/version-1.html#sidecat-ui); Work/Plan, Messaging, roles/actors, auth/resource interfaces; development internal-client QA | Can an operator understand and direct work when the lead is absent, using shared work and authority? |

The current groupings are in this guide's [component roles](#component-roles)
and [product-wide roles](#product-wide-roles) tables. The development agreement's
[accountability coverage](https://sidecat.dev/development/process.html#required-roles-and-accountability)
and development checkpoints remain mandatory regardless of the grouping.
The current manual role kit is preparation for native role assignment and
activation. Its files and credential profiles do not establish that the native
actor lifecycle is implemented.

## Apply the cycle

| At this point | Read/check | Leave in Sidecat |
| --- | --- | --- |
| Select an outcome | Product purpose, relevant requirement rows, role input, current evidence and capacity | Outcome, selected Work/Plan, owners, independent review coverage, budget and stop conditions |
| Approve implementation readiness | Concrete component calls, object ownership, failure behavior, consumers and reuse/rebuild reason | Reviewed spec/plan and any shared-contract disposition |
| Integrate | Exact source, appropriate failing/passing behavior evidence, independent review, docs and removal decisions | Findings and their disposition; exact integrated candidate |
| Build and install | The integrated source, packaging and supported configuration | An exact usable candidate for independent testing |
| Qualify an installed candidate | Functional, failure/recovery, concurrency, unfamiliar-user and documentation evidence | Scoped QA decision with observations and limits |
| Publish or cut over | Product acceptance, valid QA decision, authority/destination, installer and recovery plan | Release/activation decision and the exact artifact |
| Review the cycle | Delivered and undelivered outcomes, evidence, cost and coverage gaps | Disposition of unfinished work and a deliberate next outcome |

These are views of the development agreement's [firm checkpoints](https://sidecat.dev/development/process.html#firm-checkpoints). They do not turn guidance into
an executable workflow. Until the selected procedure is implemented and qualified
in Sidecat orchestration, the lead records how its decisions were applied and
discloses the checks that remain manual.

### Testing the delivered build

Prepare QA charters during development. Run release QA and unfamiliar-user trials
after the candidate is built, installed and usable, before release. Test the
artifact and shipped documentation. Developer tests and source review provide
earlier evidence; they do not replace this stage. A repair produces a new candidate
and repeats the affected installed checks.

### Choosing reliability work

When recovery, consistency, audit or other reliability work consumes a substantial
part of a cycle, reconsider its scope and timing. Name the real user task, the
required behavior, and any extra guarantee we chose. Compare a simpler sufficient
design and a shared mechanism where several applications need the same behavior.
Existing code placement is a revisable choice.

Assess internal development use, short external trials and production qualification
separately. Invest where the benefit justifies the cost; defer work that is
unnecessary for the selected use, with its limit stated clearly. Hold only the
scope that depends on it. Small, useful repairs need a proportionate decision;
this review should not become another costly process.

## Surface and documentation pass

At planning, select the public operations and user tasks affected by the slice.
At integration, check the shared contract and the relevant projections below.
The [development surface/testing checks](https://sidecat.dev/development/process.html#surfaces-documentation-and-testing)
set the obligation; this table is the working checklist.

| Surface | Check |
| --- | --- |
| argv / CLI | Discovery, help, inputs, readable and structured results, errors and next steps |
| MCP | Descriptions and schemas, discovery, invocation, structured results and recovery information |
| Sidecat Lisp | Operation inspection, composition, typed values and consistent effect/continuation semantics |
| Native client / bus | The same operation contract and applicable event/subscription behavior |
| Sidecat UI | The relevant operator task, selected project/environment, fresh/stale state and useful error recovery |
| Documentation | Affected man pages, examples, user and author guides, README, llms.txt and web instructions |

Prefer one operation descriptor with generated projections to manually maintained
copies. A new app should not require editing core routing or several independent
command implementations. During each release cycle, exercise every supported call surface and the
available UI paths on the installed candidate, using common acceptance scenarios
with surface-specific discovery and recovery checks. Record any missing projection
or outdated explanation. Declare unaffected surfaces explicitly
when the relationship is not obvious; do not summon every reviewer or repeat the
whole product suite for a private implementation change.

## Revision and capture

The accepted product contract is `architecture/version-1-contract.md`, revision 3.
The accepted development agreement is `architecture/version-1-development.md`,
revision 2. Both were approved on 29 September 2026. This evolving guide is
`architecture/version-1-reading-guide.md`.

Captures identify each applicable agreement's exact digest, headings, requirement IDs,
named accountability/checkpoint rows and selected role revisions. They may name the
guide revision used for selection; filenames alone do not pin an agreement.

An active assignment retains its selected agreement/role revisions until authorized
amendment. Revised reading paths cannot replace them silently; pinning does not preserve
expired or revoked authority. Adoption identifies each accepted successor explicitly.

Accepted source digests:

- Product: `sha256:5f60dcb981a0cabce8f3b33f2c4d1138a27d7dbd03b0fea7a3b29279bae043b7`.
- Development: `sha256:2f712bd83fb40459fe5a5a819893e61855e794cf82a7cbde6e17800687760537`.