@zihanw/pi-forge 0.4.1 → 0.5.1

package/docs/design/archive/0.5-full-proposal/0.5-inventory.md

@@ -0,0 +1,208 @@
+# 0.5.0 migration inventory
+
+[Design index](README.md) · [0.5 architecture plan](architecture-0.5.md) · [Architecture rules](../../../development/architecture-rules.md)
+
+Status: Phase 0 evidence; not an accepted architecture decision
+
+Date: 2026-08-17
+
+This inventory records the 0.4.1 surfaces that 0.5 must retain, migrate, remove,
+or deliberately replace. It is a characterization aid, not a promise to preserve
+every current behavior. The 0.5 plan remains authoritative, and a maintainer must
+accept any new boundary or product decision before implementation.
+
+## Snapshot and method
+
+The inventory is based on tracked source, tests, the package manifest, and
+documentation at commit `5b56096`. It lists in-repository consumers and
+documented integration surfaces. It cannot establish unknown downstream npm
+consumers; that check remains a Phase 6 release task.
+
+| Area | Current evidence | 0.5 disposition |
+|---|---|---|
+| Prompt stacks | Schema v1 files, project/global catalogs, legacy project read path, compiler, macros, slots, regex, tool/skill policy | Keep as v2 compiler/resource work; remove mutable variables; audit finalized regex; retire legacy storage compatibility on the documented path |
+| Agent profiles | Schema v1 files, project/global catalogs, model/thinking/stack preflight, apply, provenance, drift | Keep as a separate domain and service; introduce v2 only if storage changes |
+| Runtime state | One `PiForgeRuntimeState` owns resources, lifecycle values, presentation/debug state, and variables | Replace with workspace-owned resource snapshot plus separate adapter state slices |
+| Browser editor | Token-gated localhost HTTP server; host performs resource workflows and direct writes | Retain as an adapter; move resource mutation and validation into services/repositories |
+| Subagents | Main extension registers commands/tools and directly depends on `@zihanw/pi-subagent-runtime` | Extract as optional package behind a versioned public host port |
+| SillyTavern | Import command, converter, report, guide, example, tests | Remove completely; require conversion on 0.4 before upgrading |
+| Package surface | Root exports, `/subagent`, and `src/*` compatibility patterns | Replace with explicit 0.5 entries; retain only intentional public ports |
+
+## Public package and extension surfaces
+
+### Package manifest
+
+- Package: `@zihanw/pi-forge` 0.4.1; Pi entry: `dist/index.js`.
+- Public exports: package root, `@zihanw/pi-forge/subagent`, examples, and broad
+  compiled `@zihanw/pi-forge/src/*` compatibility aliases. Browser client paths
+  are explicitly blocked.
+- Pi SDK packages and `typebox` are optional wildcard peers. The repository's
+  development fixture is Pi 0.83.0; no minimum or tested Pi range is published.
+- `@zihanw/pi-subagent-runtime@0.1.0-beta.2` is currently a hard dependency.
+- `PUBLIC_API.md` and `SUBAGENT_ADAPTER_CONTRACT.md` are npm-published root
+  compatibility pointers to the authoritative reference documentation. Their
+  0.5 package-file and redirect status is not yet decided.
+
+### Root exports grouped by intent
+
+| Current surface | Evidence / consumer | 0.5 review action |
+|---|---|---|
+| Default Pi extension factory | `src/index.ts`; `pi.extensions` manifest | Keep as main package entry point |
+| Resource identity/catalog/loader helpers | Root barrel and tests | Decide whether each is a stable domain export or internal |
+| Macro/slot registration and Forge extension API | Root barrel; custom-system-status example and guide | Preserve only as an intentional trusted-extension port, compatible with immutable compilation |
+| Profile repository/resolution/application APIs | Root barrel and profile tests | Replace experimental APIs with deliberate service/domain exports if external consumers exist |
+| Subagent contract and host preparation helpers | Root compatibility re-exports and `/subagent` entry | Keep `/subagent`, but replace its current internal host-preparation surface with a versioned port |
+| `src/*` aliases | Documentation and package checks | Remove in Phase 6 after consumer audit and migration notice |
+
+The only in-repository package-style import is the public-API test of
+`@zihanw/pi-forge/subagent`. Documentation identifies trusted macro/slot
+extension authors as intended consumers. No external consumer audit is recorded.
+
+### Phase-0 public-surface decision register
+
+This is the required decision format for the final public-surface review. The
+listed dispositions are provisional until consumer audit and maintainer review;
+Phase 6 must execute this register rather than make API decisions while deleting
+exports.
+
+| 0.4 surface group | Candidate 0.5 disposition | Target entry point / migration | Known consumer | Decision status |
+|---|---|---|---|---|
+| Default extension factory | Stable | Package root default export | Pi package manifest | Provisional: retain |
+| Macro/slot and trusted Forge extension registration | Stable or experimental | Deliberate main-package extension port | Custom-system-status example; documented trusted extension authors | Pending compiler-extension contract |
+| Resource identity/catalog/loader helpers | Internal unless a named consumer requires a domain port | No `src/*` replacement by default | Root barrel and tests only | Pending consumer audit |
+| Profile repository/resolution/application helpers | Experimental or internal | Deliberate service/domain entry only if justified | Root barrel and tests only | Pending service boundary and consumer audit |
+| `/subagent` host contract | Versioned experimental host port | `@zihanw/pi-forge/subagent` | Public-API test; future optional extension | Pending host-discovery decision |
+| Root re-exports of subagent names | Remove or retain only as one-release migration shim | Direct consumers to `/subagent` | 0.4 compatibility policy | Pending consumer audit and migration decision |
+| `src/*` aliases | Remove | Intentional entries only | Compatibility documentation | Planned removal in Phase 6 |
+| `PUBLIC_API.md` and `SUBAGENT_ADAPTER_CONTRACT.md` | Retain as package pointers or replace with package-local index | Decide published-file policy with the final entries | `files` allowlist and current documentation | Pending Phase 6 public-doc decision |
+
+## Persisted resources and state
+
+### Resource files
+
+| Resource | Locations | Schema / current behavior | Migration concern |
+|---|---|---|---|
+| Prompt stack | Project `.pi/forge/prompt-stacks/*.json`; global `~/.pi/forge/prompt-stacks/*.json`; legacy project `.pi/prompt-stacks/*.json` read path | v1 `PromptStack`; scoped project-over-global resolution; loader normalizes and validates | Define v1→v2 codec, retained regex fields, `variables`→immutable `parameters`, conflict/backup behavior, and final legacy-path removal |
+| Agent profile | Project `.pi/forge/agent-profiles/*.json`; global `~/.pi/forge/agent-profiles/*.json` | v1 `pi-forge.agent-profile`; model, thinking level, relative scoped stack reference, optional auto-activation | Preserve IDs/scoped references where possible; decide whether v2 is needed and document any rewrite |
+| Main-package configuration | Project/global `.pi/forge/config.json` | `webEditor.port` | Main package owns the editor setting; keep it outside stack/profile repositories |
+| Subagent configuration | Currently project/global `.pi/forge/config.json`, `subagents.*` | Defaults, per-profile authorization, backend/timeout, unattended invocation and summary flag | Open: optional package must own parsing, validation, writes, and migration; decide whether it remains a namespaced shared file or moves to a dedicated file |
+| Trusted Forge extensions | Project/global `.pi/forge/extensions/*.{ts,js,mjs,cjs}` | Executable macro/slot registrations, loaded on trusted projects | Workspace owns registration lifecycle; compiler v2 must define the replacement extension contract |
+| Payload captures | User-selected path, commonly `.pi/forge/payloads/last.json` | Redacted provider payload, potentially sensitive | Presentation/debug artifact, not workspace resource state |
+
+### Pi session custom entries
+
+| Entry type | Stored data | Current restoration | 0.5 requirement |
+|---|---|---|---|
+| `pi-forge-prompt-stack-state` | `activeStackId` | Latest branch entry selects scoped active stack | Version/restoration and v1 selector migration policy |
+| `pi-forge-agent-profile-state` | Profile provenance or `null` | Latest branch entry drives drift status; does not reapply profile | Version/restoration policy and compatibility with profile schema changes |
+| `pi-forge-variable-state` | Mutable session variables | Latest branch entry restores variables | Remove and provide an explicit ignored/diagnostic migration path; do not write a replacement |
+
+These entry payloads have no explicit version today. This requires a state
+decision and migration notes under the architecture rules.
+
+## Runtime ownership and Pi coupling
+
+`PiForgeRuntimeState` currently holds stacks, profiles, active selection,
+profile provenance, compile inputs/variables, diagnostics, Forge-extension
+registration metadata, payload capture, and browser-facing state. Its users span
+the stack, profile, policy, web-editor, payload, lifecycle, and subagent paths.
+
+| Pi coupling | Current owner / use | 0.5 target |
+|---|---|---|
+| Lifecycle | Session, resource-discovery, tree/compact/shutdown, input/turn, compilation/context and message events | Pi adapter translates events to workspace/services and owns adapter-only transient state |
+| Compilation | `before_agent_start` and `context` provide live Pi context, clock, system options and messages | Normalize inputs once into immutable `PromptEnvironment`; preview and runtime share the compiler |
+| Tool policy | Pi active-tool APIs plus input/turn reassertion and tool-call guard | `ToolPolicyPort`; preserve baseline reconciliation with other extensions |
+| Profile application | Pi model/thinking setters plus active-stack mutation and rollback | Runtime-controller port with preflight and documented compensation semantics |
+| Extension registrations | Forge loader mutates macro/slot registries | Workspace-coordinated trusted registration lifecycle, without core importing Pi adapters |
+| Subagents | Main extension creates runtime/backends and reads shared state | Optional extension calls only the versioned Forge host capability |
+
+## Commands, tools, and HTTP adapter surface
+
+| Surface | Current operations | 0.5 disposition |
+|---|---|---|
+| `/preset` | List, status, use/disable, preview, validate, diagnostics, reload, UI, legacy migration, SillyTavern import | Keep ordinary stack operations as service calls; remove legacy migration command after documented migration and remove SillyTavern command |
+| `/profile` | List, use, save, status, preview, validate, reload, forget | Keep as thin profile-service adapter |
+| `/payload` and `/intercept` | Arm/display/save redacted next provider payload | Keep as separate debug/presentation slice; decide path-safety independently of domain resources |
+| `/forge-agent` | Backends, dry plan, approved run | Move with optional subagent integration |
+| `forge_subagent_profiles` and `forge_subagent` | Enabled-profile discovery and foreground delegation | Move with optional subagent integration |
+| Local editor HTTP API | Stack/profile list/get/validate/create/save/delete/apply/reload/activate; resources; payload; delegation config | Retain token-gated localhost adapter; map typed service results to HTTP and remove workflow/persistence from web host |
+
+The editor binds to `127.0.0.1`, uses a per-server random token, and accepts the
+token in the query/header. Browser source remains under `src/web-editor/client/`;
+generated embedded assets must not be hand edited.
+
+## Current resource mutation locations
+
+| Location | Current mutation | Phase 1 target |
+|---|---|---|
+| `web-host.ts` | Stack/profile/config reads and writes, deletes, creation, import routing | Adapter invokes repositories/services only |
+| `profile-service.ts` | Profile create/write/delete | Move filesystem behavior to profile repository and codec |
+| `preset-command.ts` | SillyTavern converted stack/report writes | Remove with SillyTavern surface |
+| `stack-migration.ts` | Legacy stack copy/delete | Retire after the documented pre-0.5 migration path |
+| `forge-config.ts` | Configuration writes | Separately owned configuration concern unless explicitly redesigned |
+| `payload-command.ts` | User-requested payload file write | Debug artifact, not a domain-resource repository |
+
+Current resource mutation has path-containment and symlink checks in several
+paths, but replacement writes are not uniformly atomic and stack mutations do
+not uniformly carry expected fingerprints. Phase 1 must characterize these
+behaviors before changing them.
+
+## Tooling and verification surface
+
+| Tooling | Current enforcement | 0.5 review action |
+|---|---|---|
+| `scripts/check-package.mjs` | Package tarball layout, wildcard Pi peers, `src/*` compatibility exports, blocked browser paths | Update with final explicit entry points and root compatibility-pointer policy in Phase 6 |
+| `scripts/check-dist.mjs` | Generated `dist/` matches authored source | Update only alongside intentional source/package layout changes |
+| `scripts/check-docs.mjs` | Local documentation-link validation | Keep links current as 0.5 guides, migration material, and redirects replace 0.4 documentation |
+| `scripts/build-web-client.mjs` | Generated embedded browser script/style synchronization | Preserve; regenerate only from authored `src/web-editor/client/` changes |
+| Public API and package tests | Root/subagent export compatibility and packed-entry behavior | Replace 0.4 compatibility assertions with the accepted public-surface register in Phase 6 |
+
+`package.json` scripts, the browser suite, build/type checks, and packed-install
+smoke tests are part of the release evidence. The final verification matrix must
+test the documented Pi range with and without the optional subagent package.
+
+## Documentation, examples, and characterization coverage
+
+### Released documentation requiring a 0.5 review
+
+- Prompt-stack schema, macro/slot, agent-profile, configuration, command,
+  debugging, delegation, web-editor, getting-started, public-API, and subagent
+  contract documentation.
+- English and Chinese user guides. Chinese internal architecture documentation
+  is not required by the plan, but user-facing breaking changes are.
+
+### Examples and tests requiring disposition
+
+| Item | 0.5 action |
+|---|---|
+| Default, image-reader, reviewer, and validation prompt-stack examples | Revalidate or migrate against schema v2 |
+| Custom system-status extension | Retain only if it conforms to the replacement template/slot extension port |
+| SillyTavern example, importer fixtures/tests, and guide | Remove after final 0.4 conversion path is documented |
+| Compiler, profile, catalog, policy, lifecycle, web-editor, and subagent tests | Preserve as characterization coverage until the responsible phase replaces them |
+| Browser editor tests | Keep through adapter migration; regenerate client assets when authored client code changes |
+
+## Phase-0 open work and exit evidence
+
+1. Record maintainer acceptance or amendment status for the proposed 0.5 plan.
+2. The [external-consumer audit](0.5-consumer-audit.md) is complete with an
+   explicit unauthenticated-search limitation. Repeat it with maintainer access
+   before Phase 6 removes exports or compatibility paths.
+3. The [template-language spike](template-language-spike.md) is complete.
+   Accept its grammar, environment, extension-port, schema, and migration
+   decisions before Phase 3.
+4. The [Pi host-discovery spike](host-discovery-spike.md) is complete.
+   Accept its event-bus host-port protocol, operation catalogue, versioning, and
+   lifecycle rules before Phase 5.
+5. Establish a supported Pi version range and packed-install test matrix.
+6. Decide Pi session custom-entry versioning and restoration semantics for
+   prompt-stack state, profile state, and removed variable state.
+7. Decide main-package versus optional-subagent ownership and storage migration
+   for `webEditor.*` and `subagents.*` configuration.
+8. Complete and accept the public-surface decision register before Phase 6.
+9. Turn repository/reload, profile-application, finalized-regex,
+   migration-artifact, and physical-package questions into accepted decisions
+   before their affected implementation phases.
+
+Phase 0 exits only when this removal/migration inventory and the resulting
+decisions are reviewed. This inventory alone authorizes no implementation
+boundary changes.

package/docs/design/archive/0.5-full-proposal/0.5-phase0-decision-drafts.md

@@ -0,0 +1,237 @@
+# 0.5.0 Phase-0 decision drafts
+
+[Design index](README.md) · [Architecture decision template](../../decision-template.md) · [Migration inventory](0.5-inventory.md)
+
+Status: proposed drafts; requires maintainer acceptance
+
+Date: 2026-08-17
+
+This document packages the remaining Phase-0 choices for review. It does not
+authorize code, schema, package, or persistence changes. Each accepted section
+may become a focused architecture decision or an amendment to the 0.5 plan.
+
+## D1: Pi compatibility and release matrix
+
+### Candidate decision
+
+Support Pi 0.83.0 as the initial documented minimum, because it is the checked
+development fixture and supplies the extension/event APIs used by pi-forge.
+Treat compatibility as a rolling list of explicitly tested Pi versions, not a
+semver range inferred from wildcard peers. Test 0.83.0 and npm `latest` (0.84.2
+when this draft was written) for every 0.5 release candidate, including packed
+main-only and main-plus-optional-subagent installs. Keep Pi packages as wildcard
+optional peers so Pi supplies one coherent SDK instance.
+
+### Alternatives
+
+- Claim every Pi version through a semver range: reject, because wildcard peers
+  and Pi's frequent 0.x releases do not prove behavioral compatibility.
+- Pin Pi dependencies inside pi-forge: reject, because it risks duplicate Pi
+  runtimes and conflicts with Pi package loading.
+
+### Acceptance evidence
+
+Document exact tested versions, Node version, packed-install commands, and
+main-only/optional-package results in release notes. Run a scheduled latest-Pi
+probe that reports compatibility but does not silently widen the supported list.
+
+## D2: Pi session custom-entry versioning
+
+### Candidate decision
+
+Keep the existing prompt-stack and profile custom entry types, but make every
+newly written payload an envelope with `schemaVersion: 1`. Read unversioned 0.4
+entries through explicit legacy decoders only; do not rewrite historical Pi JSONL
+entries. Ignore unknown versions and malformed entries with a bounded diagnostic.
+
+The latest valid entry in the active branch remains authoritative. Restoring a
+selector or provenance must never apply a profile or mutate Pi runtime state.
+`pi-forge-variable-state` is never restored or written in 0.5; its presence
+produces one migration diagnostic per restoration, not a variable store.
+
+### Alternatives
+
+- Rename all custom entry types: reject unless a real collision requires it;
+  existing type names are useful migration anchors.
+- Continue unversioned free-form payloads: reject; it violates the state rules.
+- Automatically append replacement entries while restoring: reject; opening a
+  historical session must not mutate it.
+
+### Acceptance evidence
+
+Characterization tests cover legacy/current/unknown/malformed entries, branch
+selection, compaction/tree navigation, missing resources, and no variable-state
+resurrection.
+
+## D3: configuration ownership after subagent extraction
+
+### Candidate decision
+
+The main package owns `webEditor.*` in `.pi/forge/config.json` and its global
+equivalent. The optional package owns all subagent configuration, parsing,
+validation, mutation, and diagnostics in dedicated
+`.pi/forge/subagents.json` and `~/.pi/forge/subagents.json` files. Main pi-forge
+does not read, write, validate, or surface subagent policy when the optional
+package is absent.
+
+The optional package may read the 0.4 `config.json.subagents` section only in a
+one-time migration mode. It writes no automatic migration, preserves the legacy
+section, and reports conflicts rather than merging silently.
+
+### Alternatives
+
+- Keep a shared `config.json` namespaced section: lower migration cost, but
+  creates shared-file coordination and leaves main-package ownership ambiguous.
+- Preserve main-package parsing of `subagents.*`: reject; it contradicts the
+  optional package boundary.
+
+### Acceptance evidence
+
+Test absent optional package, untrusted project, project/global precedence,
+legacy-config migration, conflict reporting, and deletion/config cleanup.
+
+## D4: resource repositories and workspace snapshots
+
+### Candidate decision
+
+Repositories own all stack/profile discovery and mutation. A codec is the only
+source of parse, normalize, validate, serialize, and content fingerprint logic.
+Every write/delete receives an expected fingerprint when replacing an existing
+resource; mismatch returns a typed conflict without writing.
+
+`ForgeWorkspace` serializes reloads and publishes an immutable complete
+snapshot with a monotonic revision. There is no filesystem watcher in 0.5:
+explicit reload and existing lifecycle-driven reload are the only refresh paths.
+Invalid/missing resources appear as diagnostics in the published snapshot, while
+resolution and activation fail closed. A selected active resource that becomes
+invalid or disappears is not active until a later complete reload resolves it.
+
+Filesystem repositories use temp-file-plus-rename replacement where supported,
+validate containment before every mutation, and clean failed temporary files.
+
+### Alternatives
+
+- Keep synchronous adapter writes: reject; it preserves duplicate persistence
+  workflows and bypasses consistent conflict handling.
+- Publish each catalog independently: reject; profiles could resolve against a
+  different stack generation.
+- Add file watching during the refactor: defer; it is a new state/lifecycle
+  feature outside 0.5 scope.
+
+### Acceptance evidence
+
+Test external edit conflicts, atomic-write failures, reload serialization,
+mixed valid/invalid catalogs, scoped shadowing, active deletion, and consumers
+never observing half a stack/profile graph.
+
+## D5: profile-application transaction semantics
+
+### Candidate decision
+
+`AgentProfileService` resolves and validates model, authentication, thinking,
+stack, and tool policy before any Pi mutation. It delegates mutations to a
+runtime-controller port in this order: model, thinking level, active stack/tool
+policy. It records provenance only after all three succeed.
+
+On failure, the service compensates in reverse order using the captured prior
+state and reports every failed compensation. This is a best-effort transaction,
+not an atomic Pi-host transaction; an unset prior model that Pi cannot restore
+is an explicit residual failure. Adapters render the typed result but do not
+attempt their own rollback.
+
+### Alternatives
+
+- Call Pi setters directly from commands/web handlers: reject; it duplicates
+  transaction behavior.
+- Describe this as atomic: reject; Pi setters have externally visible effects
+  and no common rollback primitive.
+
+### Acceptance evidence
+
+Integration tests cover each failure point, unexpected thinking-level clamp,
+missing stack after preflight, rollback failure, provenance write timing, and
+browser/command equivalence.
+
+## D6: regex and v1-to-v2 migration
+
+### Candidate decision
+
+Retain deterministic outgoing `history` and `compiled` regex transforms in v2,
+after schema characterization. Remove `display`/`both` as unsupported 0.4
+configuration and remove destructive `finalize` transforms: they alter stored
+assistant transcript after streaming and sit outside deterministic compilation.
+
+Provide one explicit v1-to-v2 migration utility with dry-run default, per-file
+diagnostics, no overwrite unless requested, backup/copy before replacement, and
+no source deletion. It mechanically converts only documented safe fields and
+emits error-level diagnostics for mutable variables, custom macros/slots,
+removed regex effects, and unsupported template constructs. Users run the final
+0.4 storage migration before the v2 utility; 0.5 does not retain the legacy
+storage migration command.
+
+### Alternatives
+
+- Retain `finalize`: requires a separate persistent-transcript ownership and
+  previewability decision; defer rather than retain incidentally.
+- Silently drop unsupported fields: reject; migration must make behavior loss
+  visible.
+- Keep both legacy storage and v2 migration commands indefinitely: reject;
+  conflicts with the breaking-cleanup policy.
+
+### Acceptance evidence
+
+Fixture coverage proves dry runs do not write, conflicts/backups are explicit,
+repeated runs are idempotent, and every removed field is reported. The final
+0.4→0.5 user guide documents exact ordering and recovery.
+
+## D7: physical package topology
+
+### Candidate decision
+
+Do not publish `pi-forge-core` in 0.5. Establish its boundaries as enforced
+internal modules first. Publish only `@zihanw/pi-forge` and the optional
+`pi-forge-subagents` package in Phase 5. The optional package uses documented
+`@zihanw/pi-forge/subagent` host-port messages and Pi wildcard peers; it has no
+dependency on core internals, web-editor modules, or a private copy of runtime
+state. Extract core as a third package only after 0.5 if a named consumer proves
+that package boundary necessary.
+
+### Alternatives
+
+- Introduce a workspace and three published packages immediately: reject; it
+  adds package/version/build complexity before interfaces are characterized.
+- Let optional subagents import internal core modules: reject; it defeats the
+  host-port boundary.
+
+### Acceptance evidence
+
+Packed installs prove main pi-forge works with no subagent runtime/package, and
+the optional package works only through the versioned host protocol.
+
+## D8: final public surface
+
+### Candidate decision
+
+Use the public-surface register in the migration inventory as the Phase-6
+allowlist. The root default extension remains stable. `/subagent` is the sole
+versioned experimental host port. `src/*` aliases and root subagent re-exports
+are removed. Resource/catalog/loader/profile helpers become internal unless the
+consumer audit names a consumer and an intentional domain/service entry is
+accepted. Macro/slot registration remains provisional pending the immutable
+template/slot-port decision. Retain the two root documentation pointer files as
+offline redirects in the 0.5 package unless the package documentation layout
+otherwise provides a stable equivalent.
+
+### Acceptance evidence
+
+Update package exports, `files`, package checks, public-API tests, reference
+docs, changelog, and migration guide in one Phase-6 change. Test rejection of
+all removed subpaths from a packed install.
+
+## Maintainer choices required
+
+1. Accept, amend, or reject the host-RPC and `forge-v1` template spike
+   candidates.
+2. Choose D3 dedicated subagent files versus a namespaced shared config file.
+3. Choose D6 removal versus separately designed retention of `finalize` regex.
+4. Accept/amend D1, D2, D4, D5, D7, and D8 before their affected phases.

package/docs/design/archive/0.5-full-proposal/README.md

@@ -0,0 +1,12 @@
+# 0.5.0 full architecture proposal (archive)
+
+Status: archived 2026-08-18 as the long-term target.
+
+The active, executable 0.5.0 scope is now the [lean 0.5.0 architecture plan](../../architecture-0.5.md). The documents here were the original Phase-0 proposal and evidence base. They remain authoritative for the long-term target architecture, not for current 0.5.0 lane sequencing.
+
+- [Full 0.5 architecture plan](architecture-0.5.md) — original six-phase target and release gates.
+- [Migration inventory](0.5-inventory.md) — 0.4 surface characterization.
+- [Public-consumer audit](0.5-consumer-audit.md) — known external consumer evidence.
+- [Phase-0 decision drafts](0.5-phase0-decision-drafts.md) — original open decisions D1-D8.
+- [Template-language spike](template-language-spike.md) — evidence behind `forge-v1`.
+- [Pi host-discovery spike](host-discovery-spike.md) — evidence behind the event-bus host port.