Documentation: Architecture page for Product/Instance concept

[enthali]

Motivation

The Product/Instance separation is a central architectural concept in syspilot, but it is not explained anywhere for end users. New users (and the growing number of GitHub stars suggests there will be more) currently have to piece it together from methodology.md, naming conventions, and changelog entries.

Problem

What exists today:

• docs/methodology.md — technical mechanics (directories, IDs, write boundaries), not the why
• docs/namingconventions.md — mentions INST_<FAMILY>_ prefix, no conceptual explanation
• copilot-instructions.md — shows directory layout but doesn't explain the model
• Change document archive — full decision history, but nobody reads that

What's missing: A conceptual overview page that explains why the separation exists and how it works.

Proposed Content (docs/architecture.md)

1. Why the separation?

   • Generic agents reusable across projects
   • Each project has its own processes (release flow, CI/CD, branching...)
   • Product updates don't break project-specific customizations

2. What is Product, what is Instance?

   • Product = the agent family as a library/framework (syspilot/)
   • Instance = project-specific configuration (docs/inst/syspilot/)
   • Analogy: Product is the OS, Instance is the configuration

3. How do they relate?

   • Instance specs link to Product specs via sphinx-needs :links:
   • Setup Agent installs Product artifacts into .github/
   • Instance overrides/extends, Product stays stable

4. Concrete example — Release Agent: generic product + project-specific instance spec

5. Update safety — How to customize without breaking on updates (configure via INST specs, not by editing .github/agents/ directly)

Placement

• docs/architecture.md — framework-level, applies to all families
• Link from methodology.md: "For the concept behind Product/Instance, see architecture.md"

Scope

Documentation only, no code changes. Should also get a REQ/SPEC under the DOC theme.