Release Architecture Memory platform foundation (v1.5.0).

Ship Memory through ArchitectureContextEnvelope, product constitution, and Architecture Moments discovery — freeze the foundation before surfaces or AI.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: gubakareem

CHANGELOG.md

@@ -7,14 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-07-23
+
 ### Added
 
-- GoF design-pattern generators (distinct from architecture presets):
-  - `strategy` — contract, default/alternative strategies, strategy context
-  - `state` — contract, draft/published/archived states, state context with transitions
-  - `singleton` — `{Model}Registry` with classic Singleton semantics (documents Laravel container preference)
-  - `abstract-factory` — component factory family (notifier + serializer) + client; separate from Eloquent `factory`
-- [ADR-0007](docs/adr/0007-event-bus-for-engine-extensibility.md): event bus for engine extensibility (planned for **v1.5 / Integration** — public extension events, compatibility promise, observational listeners).
+- **Architecture Memory platform** (Workspace): append-only events, baselines, stories, decisions, intelligence, guidance, journeys, standards, governance, evolution, learning, collaboration, knowledge transfer, questions, conversations, decision history, identity, communication, and architecture context.
+- **ArchitectureIdentitySnapshot** — stable identity contract with inertia and identity history; `identity_observed` only via explicit `observe()`.
+- **Architecture Brief** (Phase 16) — living transferable understanding with Audience (`developer` / `architect` / `contributor`); not static documentation.
+- **Architecture Context** (Phase 17) — “What should I know before I touch this?” composition from identity, decisions, evolution, and guidance.
+- **ArchitectureContextEnvelope v1.0** — stable pre-AI boundary for UI · IDE · PR · AI; `can_explain` / `can_modify`; typed `allowed_questions`.
+- CLI: `architect:ask`, `architect:workspace` enhancements; Ask is read-only.
+- Product constitution: [VISION.md](VISION.md), [philosophy](docs/philosophy.md), [roadmap](docs/roadmap.md), [Architecture Moment Map](docs/architecture/moments.md) (Phase 18 discovery — evidence before surfaces).
+- [ADR-0008](docs/adr/0008-visualize-architecture-assistant-ux.md): Architecture Workspace UX boundary.
+- Unit tests for memory, controlled change, fix proposals, and workspace services.
+
+### Changed
+
+- Product positioning: **architecture continuity system** — preserves architectural intent; AI speaks from architectural memory, never replaces it.
+- Foundation frozen at Envelope; next work is evidence collection (Architecture Moments), not engine expansion.
 
 ## [1.4.3] - 2026-07-22
 

CONTRIBUTING.md

@@ -2,6 +2,22 @@
 
 Thank you for considering contributing to LaraArchitect! Contributions of all kinds are welcome: bug reports, feature ideas, documentation improvements and pull requests.
 
+## Before you write code
+
+1. Read **[VISION.md](VISION.md)** — why the project exists (North Star, principles, constitution).
+2. Read **[docs/philosophy.md](docs/philosophy.md)** — the project constitution.
+3. Skim **[docs/roadmap.md](docs/roadmap.md)** and the **[ADR index](docs/adr/README.md)** — how we build.
+
+**Every new feature should strengthen the engine or improve the developer’s daily workflow inside the Workspace.** If it does neither, reconsider.
+
+**Permanent principle:** *AI speaks from architectural memory — never replaces it.*
+
+**Feature checkpoint:** *Which existing architectural memory does this feature help a developer access?* If unclear, it probably does not belong here.
+
+Before proposing AI or language-layer work, ask: **Does this help developers understand existing architectural intent?** If it would create new architectural truth, it does not belong in the AI layer.
+
+Maintainers releasing versions: see **[MAINTAINERS.md](MAINTAINERS.md)**.
+
 ## Reporting issues
 
 Before opening an issue, please:

MAINTAINERS.md

@@ -0,0 +1,90 @@
+# Maintainer notes
+
+> For future you. Things nobody else should have to rediscover.  
+> Contributors start at [VISION.md](VISION.md). Users start at the [README](README.md).
+
+## Release checklist
+
+- [ ] `composer format` (Pint)
+- [ ] `composer analyse` (PHPStan / Larastan)
+- [ ] `composer test` (PHPUnit — full suite)
+- [ ] Update `[Unreleased]` → version section in `CHANGELOG.md`
+- [ ] Verify **public API** surface (below) — no accidental breaks
+- [ ] Review **ADR impact** — does this change need a new ADR or an amendment?
+- [ ] Check **backward compatibility** (SemVer; BC aliases; config merge)
+- [ ] Docs still match behavior (`README`, `docs/`, `VISION.md` if product intent shifted)
+- [ ] Tag release (`vX.Y.Z`) and push tag
+- [ ] Packagist / GitHub release notes as needed
+
+## Public API (stable — SemVer)
+
+Treat breaking changes here as **major** (unless clearly experimental and documented).
+
+### Architecture engine
+
+| Symbol | Role |
+| --- | --- |
+| `ArchitectureEngine` | Entry point for analyze / lint |
+| `AnalysisResult` | Immutable analysis output |
+| `LayerRegistry` | Layer definitions |
+| `ArchitectureRule` | Rule contract |
+| `RulePack` | Pack of rules |
+| `DependencyExtractor` | Extraction contract |
+| `Renderer` | Report rendering contract |
+| `MetricCalculator` | Metrics contract (plugins later) |
+| `SuggestionProvider` | Suggestions contract (plugins later) |
+| Value objects / IDs used in public results | e.g. `Violation`, `Hotspot`, `Baseline`, `RuleId`, `LayerId`, `NodeId`, … |
+
+### Workspace read model (Experience — evolving)
+
+| Symbol | Role |
+| --- | --- |
+| `WorkspaceService` | Builds `WorkspaceSnapshot` from analysis + context |
+| `FixProposalService` | Builds `FixProposal` for Preview (no Apply yet) |
+| `WorkspaceSnapshot` | Immutable payload (`schema_version` 1.1) for UI/CLI/adapters |
+| `FixProposal` · `FileChange` · `VerificationPlan` · `FixConfidence` · `FixRisk` | Preview / verification contract |
+| `WorkspaceContext` / `Finding` / `WorkspaceIssue` / `IssueExplanation` / `WorkspaceAction` / `WorkspaceHealth` | Domain concepts |
+| `WorkspaceId` · `ContextId` · `FindingId` · `IssueId` · `ActionId` · `SessionId` · `FixProposalId` | Typed identities |
+
+Treat additive snapshot fields as minor; removing/renaming fields as major once declared stable in a release.
+
+### Generation (application-facing)
+
+| Symbol | Role |
+| --- | --- |
+| Generator contract + registered patterns | `make:module` / feature / wizard surface |
+| Published config keys under `lara-architect.generation` | Presets, namespaces, generators |
+| Runtime bases | e.g. `ArchitectRepository`, `ArchitectService`, … (+ BC aliases) |
+
+### Extension events (when ADR-0007 ships)
+
+Public lifecycle events + `ArchitectureEvent` contract — SemVer-stable per ADR-0007.
+
+## Internal (no compatibility promise)
+
+May change in any minor/patch without notice. Do not depend on these from app code or sibling packages.
+
+| Symbol | Role |
+| --- | --- |
+| `DependencyGraph` | Graph structure |
+| `RegexExtractor` | Default extractor implementation |
+| `FileScanner` | Filesystem scanning |
+| `EngineFactory` wiring details | Construction internals |
+| Scanners / use-case helpers not exported as API | — |
+| Stub file paths / private generator helpers | — |
+
+When unsure: if it is not documented as public here or in the README/engine docs, treat it as **internal**.
+
+## Product discipline
+
+1. Read [VISION.md](VISION.md) and [docs/philosophy.md](docs/philosophy.md) before large changes.
+2. Prefer strengthening the **engine** or the **Workspace experience** over unrelated features.
+3. **Enterprise** stays a future direction until the open-source edition proves the architecture — do not build it early.
+4. Update the [ADR index](docs/adr/README.md) when adding a decision record.
+
+## Useful links
+
+- [Roadmap](docs/roadmap.md)
+- [Architecture notes](docs/architecture/)
+- [ADR index](docs/adr/README.md)
+- [Contributing](CONTRIBUTING.md)

README.md

@@ -1,11 +1,41 @@
-# LaraArchitect
+# Lara Architect
 
-**Build, enforce, analyze, and evolve Laravel architecture.**
+**Architecture Memory and Improvement Platform for Laravel**
 
-LaraArchitect is an architecture operating system for Laravel — not just a generator. It covers the full lifecycle:
+The Composer package `karim-ashraf/lara-architect` is the entry point. The product vision is a **platform** (core + UI + future integrations) — see [VISION.md](VISION.md) and [docs/architecture/platform.md](docs/architecture/platform.md).
+
+Lara Architect helps you generate solid structure, catch layer violations early, remember what worked, and continuously improve how your app is built — so architecture stays intentional as the codebase grows.
+
+```bash
+composer require karim-ashraf/lara-architect
+
+php artisan architect:new          # generate a module the right way
+php artisan architect:lint         # enforce layer rules
+php artisan architect:analyze      # see health, hotspots, structure
+php artisan architect:workspace    # context + issues + explain (Workspace snapshot)
+php artisan architect:ask "why ProductService exists"  # Phase 13 — living knowledge query
+```
+
+| You want… | Start here |
+| --- | --- |
+| **To use it** | This README → [Getting started](docs/getting-started.md) |
+| **To contribute** | [VISION.md](VISION.md) → [docs/](docs/index.md) → [ADRs](docs/adr/) |
+| **To maintain / release** | [MAINTAINERS.md](MAINTAINERS.md) |
+
+---
+
+**Lara Architect Platform** — package is the entry; platform is the vision ([VISION.md](VISION.md)).
+
+| Install | You get |
+| --- | --- |
+| `karim-ashraf/lara-architect` | Core engine · memory · intelligence · guidance · learning |
+| + `karim-ashraf/lara-architect-ui` | Architecture Workspace at `/architect/workspace` |
+| + future packages | Debugbar · VS Code · GitHub · AI · Enterprise |
+
+Lifecycle:
 
 ```
-Design  →  Generate  →  Analyze  →  Enforce  →  Evolve
+Design  →  Generate  →  Analyze  →  Enforce  →  Visualize  →  Integrate  →  Platform
 ```
 
 | Pillar | What it does |
@@ -14,7 +44,9 @@ Design  →  Generate  →  Analyze  →  Enforce  →  Evolve
 | **Generate** | `make:module`, `architect:feature`, `architect:new` wizard |
 | **Analyze** | Dependency graph, layer counts, hotspots (`architect:analyze`) |
 | **Enforce** | Declarative layer rules + baseline (`architect:lint`) |
-| **Evolve** | Health score & actionable suggestions (v1.4.1 / v1.6) |
+| **Visualize** | Architecture Workspace via [lara-architect-ui](../lara-architect-ui/README.md) ([ADR-0008](docs/adr/0008-visualize-architecture-assistant-ux.md)) |
+| **Integrate** | Event bus / public extension events ([ADR-0007](docs/adr/0007-event-bus-for-engine-extensibility.md)) |
+| **Platform** | Sibling packages around a small, trustworthy core ([platform.md](docs/architecture/platform.md)) |
 
 Under the hood sits a **framework-agnostic ArchitectureEngine** — Artisan commands are thin adapters. You can analyze a codebase with no Laravel bootstrap:
 
@@ -293,9 +325,14 @@ php artisan architect:lint --format=json
 # Layer counts + violations + hotspots
 php artisan architect:analyze
 php artisan architect:analyze --format=json
+
+# Workspace snapshot — current context, issues, explain (UI adapters consume the same JSON)
+php artisan architect:workspace --context=ProductController
+php artisan architect:workspace --format=json
+php artisan architect:workspace --explain="<issue-id>"
 ```
 
-### Baseline (adopt on day one)
+The Workspace command builds a **WorkspaceSnapshot** read model from the engine ([spec](docs/architecture/workspace.md)). React / Debugbar / VS Code will share that payload later.
 
 Existing apps often have hundreds of violations. Freeze them so only *new* ones fail CI: