businesslens 0.7.2 → 0.9.0

package/CHANGELOG.md

@@ -5,7 +5,434 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.9.0] - 2026-09-04
+
+### Added
+
+- **Entity — one resource type for every thing the Product keeps or reasons
+  about.** Identity, not storage, is the test. An Entity carries named facts,
+  optional states, and relations in product language; implementation types,
+  keys, indexes, join records, and regenerable representations stay out.
+- **Entity relations state both ends.** `one-to-one`, `one-to-many`, and
+  `many-to-many` read from the declaring Entity to its target; the inverse is
+  derived so two files cannot disagree. Entity pages and the *What it keeps*
+  topology view render the product's own relationship graph.
+- **Business Rules can express authorization.** An Entity target selects an
+  operation, facts, states, and optional Contexts. `permits` grants name
+  actors, a related Entity path, self, unattended work, or configuration, with
+  optional fact and state conditions. `lint` rejects Steps and Screens that no
+  applicable grant can permit, without claiming runtime authorization has been
+  proved.
+- **A Scenario Step says what it does to the Product's things.** Every Step
+  carries `entities: []` or entries shaped as
+  `{ entity, as, effect, from, to }`, where `effect` is
+  `creates|changes|removes|reads`. Lifecycles and reverse edges are composed
+  from acceptance Steps rather than authored a second time.
+- **Unattended Scenarios.** A first condition Step may state
+  `unattended: true` for schedules, expiry, retry, and other Product-owned
+  behavior with no Actor.
+- `agent` joins the Interface types, and an Interface may own shared Screens
+  beside its Experiences. A shared Screen is inside every Experience of its
+  Interface: a Capability it exposes must be available in each, a Step on it is
+  inside a Capability's availability only when every Experience is, and that
+  Step counts as Scenario coverage for each.
+- **A Domain states what its Boundary excludes**, in the authored folder and on
+  the wire.
+- **The Product Report renders every Entity edge.** Entities have a rail entry,
+  collection, page, search results, facts, relations, composed lifecycle, and
+  topology presence. An Entity with States reads its lifecycle as a state
+  machine on its own tab, with each selecting Rule's grants in full. Scenario
+  Steps show what they create, change, remove, or read; Journey outcomes
+  summarize what they leave behind; Rules read their grants as sentences.
+- **`spec/rejected.md`** — shapes designed far enough to be costed and then
+  chosen against, so the same argument is not had twice. It binds nothing and
+  takes rejections and deferrals only: never a plan, a status, or a file
+  reference. Entries are appended, so reopening a decision means a superseding
+  entry rather than an edit. It carries what a format or report change most
+  often re-proposes — tags and free-form metadata, a glossary resource type,
+  typed facts, `actors/` as its own collection, permission on a Capability
+  target, `transitions` on the Entity, the permission algebra's discarded
+  spellings, and Blueprint provenance.
+- BusinessLens now keeps a reviewed Product Model of itself. The Content Feed
+  Reader Blueprint and golden Fixture Shop were expanded to exercise Entities,
+  relations, lifecycles, unattended behavior, and permission Rules.
+
+### Changed
+
+- **Folder schema 8 and Product Report v13 are the only accepted contracts.**
+  Historical reports are refused rather than migrated. The report SDK exports
+  `ProductReportV13Schema`, `ProductReportV13`, the unversioned current
+  aliases, Entity/fact/relation types, Step effect types, and grant types.
+- **A Capability no longer declares Entities and an Entity no longer declares
+  transitions.** Scenario Steps are the single source of truth for what happens
+  to the things the Product keeps.
+- `## Information kept` is a list of uniquely named facts, so a Rule can govern
+  one fact exactly. `## Product states` is retired.
+- Behavioral ids are verb-noun and reuse vocabulary the model already declares.
+  Entity, Domain, and Business Rule ids do not begin with a verb. The linter
+  derives these naming findings rather than asking an author to judge them.
+- Whether an Interface needs Experiences, and whether it divides, is derived
+  rather than judged: audiences are disjoint when no available Capability
+  bridges them, with the counterpart exception for symmetric platform pairs.
+  Interface entry-point keys may name the Interface's type or another Interface
+  from which it is reached.
+- A Business Rule governs at least two behaviors or an independent Context, and
+  a Domain states what its Boundary excludes. Both are now linted.
+- **The installer decides ownership by its manifest alone.** A directory that
+  merely names a skill and mentions BusinessLens is somebody else's; retired
+  skills are removed only when the manifest recorded them; every harness is
+  checked before any is written, so a refusal leaves nothing changed. This is
+  visible on upgrade: an installation made before the marker existed carries no
+  proof it is ours, so `install` and `update` refuse it with *Refusing to
+  overwrite … Pass `--force`*. One `--force` re-adopts it, and every later run
+  is marked.
+- `businesslens-map`, `businesslens-ideate`, and the authoring branches of
+  `businesslens-verify` settle undetermined boundary, granularity, naming, and
+  acceptance calls in rounds before writing. They attach the evidence they read
+  and surface remaining judgment calls explicitly; ideate's proposed delta ends
+  with a `Judgment calls` section, as map's already did.
+- `businesslens-verify` re-derives findings from the current model and
+  repository, verifies Entity facts, states, relations, composed transitions,
+  Step effects, and Rule grants, and never persists a workflow ledger.
+- The docs define each resource type on its owning page. Actor guidance moved
+  into Entities, Capability and Journey pages own their Scenario fields,
+  Business Rules owns permission semantics, and the catalog transport — the
+  report media type and its `version` parameter — is written where a catalog
+  operator reads it.
+- The open page tab lives in the URL (`t`), so a Lifecycle or Scenarios tab
+  survives a refresh and can be linked.
+- **The design record under `plans/` is retired; the constraints it carried
+  moved into the registers that govern them.** `AGENTS.md` gains *How format
+  decisions are judged* — the shipped agent as the standard a rule must meet,
+  the ranked quality axes, empirical double-authoring, descriptive and
+  generative use judged equally, and the pull-request diff as the binding human
+  surface. Its report viewer standards gain four rendering rules and the
+  four-row test for making a section render as more than prose.
+
+### Removed
+
+- **`actors/` is no longer a collection, and Actor is no longer a resource
+  type.** A person or system that acts is an Entity with
+  `kind: person|system` and `acts: external|internal`. Actor remains a role.
+
+### Fixed
+
+- **`blueprint pull` asks for the report version it can read, and refuses
+  another.** The Accept header is derived from the schema's major, and a
+  catalog answering with a different `version` parameter is refused before the
+  body is parsed. A report of another schema version, from a catalog or a file,
+  is refused in one sentence naming both versions instead of a Zod issue dump.
+- **`blueprint open` and `pull` keep the author's coverage prose.** Only
+  `method` is rewritten, as the report contract says; the note that
+  implementation alignment has not been verified here now lives in `method`
+  with the other origin claim, and `limitations` and `rationale` come through
+  exactly as authored.
+- **An Experience's `interfaceIds` is exactly the Interface its id names.**
+  Expansion files an Experience by its qualified id, so a list saying anything
+  else was a second encoding of containment — a report could validate under one
+  Interface and expand under another.
+- The stable viewer keeps the current page and its filters through a recompile,
+  so `businesslens view` can stay open while the model is edited.
+- The packed Nuxt Layer consumer, viewer documentation, and package manifest
+  stay aligned with the current report major; generated Layer `node_modules`
+  are excluded from the npm tarball; and `check-repo` pins both registers and
+  the CLI header to the report schema's major, so the version cannot go stale
+  in prose the way it once did in code.
+
+### Security
+
+- **The installer follows no name it did not write.** The installation manifest
+  is read out of the target repository, which BusinessLens treats as untrusted,
+  and every name it records reaches a recursive remove. A `skills` entry that is
+  not a plain directory name now invalidates the marker, a recorded name this
+  Product could not have written is left alone, and every removal must resolve
+  to a direct child of the skills directory — so a crafted manifest can no
+  longer point `install` at a directory outside it.
+
+## [0.8.0] - 2026-08-25
+
+### Added
+
+- **Co-located assets.** Files beside `<type>.md` are product assets owned by
+  the entity; anything under the reserved `implementation/` directory
+  describes this realization and stays home. Class comes from the path, which is
+  the only rule a tool writing a capture on CI can satisfy. An optional
+  `assets:` list titles and scopes those files without ever setting their class,
+  and unlisted files stay legal.
+- An optional `state:` on a reference or asset, valid only on a Screen and
+  validated against its `## Product states`, so several captures of one view are
+  placed beside the state each depicts instead of arriving as a flat list.
+- A `prd` Reference kind for attaching a product requirements document as
+  `intent` or `context` without making that external document the Product Model
+  authority.
+- An optional ordered `screens:` list on an Interface or Experience declaring
+  reading order over its own children. Reachability stays with the tree.
+- `businesslens view` serves repository files from a read-only, extension-
+  allowlisted mount, and the report viewer renders local `visual` references and
+  co-located assets as thumbnails instead of inert text.
+- **Every entity has a page**, at its own URL, with the authored body at full
+  width — steps, inline routes, decision points, screen states, rule statements,
+  connections, and references are no longer confined to a drawer. Every page
+  has Overview; Capability and Journey pages alone add Scenarios.
+- **A concrete Actor's marker draws what it is.** The Actor mark carries the
+  authored `kind` as its silhouette — a person or a system, at the size every
+  other kind's mark uses — and the Product-boundary `relationship` is written as
+  a word where each reading has room for it. A Scenario Step names its Actor
+  with that mark in a chip that opens the Actor, rather than as prose.
+- The open section and the open entity page live in the URL, so a report has
+  deep links, a working browser back button, and a refresh that lands where it
+  left. `BusinessLensReportViewer` exposes both as bindable models.
+- Each collection states the question it answers and the derivation behind its
+  reading order, in the vocabulary the named topology views already use.
+- Every collection opens grouped by the containment the format declares for it,
+  and says so when an entity relates to more than one group.
+- Counterpart Screens, Experiences and Interfaces cross-link from their pages:
+  the same thing on another Interface is named as such rather than appearing to
+  be a duplicate row.
+- One entity's neighbourhood is drawn on the named Topology canvas, at a width
+  that can render it, when the reader chooses the page's Neighbourhood action.
+- The stable BusinessLens Product Report: an entity-first browse, search,
+  scenario, journey, and named-topology experience over one complete report
+  projection. It renders every authored entity on its page while ranking
+  collection and Overview readings for repeated human use.
+- A shared Vue Flow foundation in the report-viewer layer (`@vue-flow/core` with a
+  `@dagrejs/dagre` layered layout, both optional peer dependencies): one
+  entity box and one container box for nine visual categories (with both
+  Scenario types distinguished in content), a fixed relation-verb
+  vocabulary, a measured Interface → Experience → Screen containment map, a
+  sitemap of the same hierarchy drawn either as a top-down tree or radially
+  from the Product core, plus focused entity filtering on the named Topology
+  surface.
+
+### Changed
+
+- **Context is now the single location concept.** Folder schema 6 replaces
+  scalar availability boundaries and Scenario Places with one strict
+  `{ place: ... }` Context shape across Capability availability, Scenario
+  Steps, and Business Rule selectors. A Context place resolves to an Interface,
+  Experience, or Screen; Screens derive their place from their path and declare
+  no availability of their own.
+- Product Report v10 mirrors the same model with `{ placeId: ... }` Contexts,
+  removes the former availability and Place wire records, and is the only
+  accepted report version. The CLI, report SDK, Product Report, bundled skills,
+  fixtures, and Content Feed Reader Blueprint consume schema 6 and report v10
+  directly.
+- Product Model terminology now names the Interface → Experience → Screen
+  hierarchy directly. The under-defined “surface” alias, including
+  `surface-parent`, surface-tree IDs, and the former Delivery surfaces view, has
+  been replaced by concrete entity names and `screen-parent`.
+- Product Report entity readings present authored Capability Context once
+  instead of repeating it in the fact strip and under “Available in.” Derived
+  Journey and Scenario Contexts stay with their concrete routes, Screen
+  placement stays in identity, and Rule Context selectors stay with
+  applicability. Journey starting places retain the exact first route Context
+  and appear as “Starts at”; raw entry-point routes remain report data rather
+  than human-facing report content.
+- Collection rows, relations, search results, and topology entities open their
+  URL-backed pages directly. References stay in Overview, Neighbourhood opens
+  Topology, and the inspector and slideover are removed. The private report
+  experiment layer remains under the final `report-viewer-lab` name with no
+  active report experiments; the background audition remains independent in
+  `theme-lab`.
+- **Capability and Journey Scenarios share one route-and-Steps model.** Every
+  Scenario now owns named `routes` and one ordered, typed `steps` list. An Actor
+  Step names its responsible Actor, a Journey Step may name its Capability, and
+  a contextualized Step maps every route to its exact Interface, Experience, or
+  Screen. Route-neutral Steps remain first-class without a Context. The
+  separate Journey
+  `flow`, `operation`, stage ids, per-Step route objects, Scenario-wide Actors
+  and availability, authored Screen Scenario backlinks, and Markdown `## Steps`
+  are removed. Folder schema 3 and Product Report v7 are no longer accepted;
+  this release has no compatibility reader.
+- Every Interface now declares one required interaction `type` (`web`,
+  `mobile-app`, `desktop-app`, `cli`, `api`, `webhook`, `messaging`, `voice`,
+  or `device`). Reports preserve it directly and use it to distinguish
+  Interface contexts visually instead of guessing from ids or route names.
+- A Journey Step names a durable Capability, never a Capability Scenario, while
+  its text states the concrete observable action or condition. Capability
+  Scenarios may split and merge without leaving dangling Journey composition
+  references.
+- **Journey pages have one Scenario reading.** The peer `Flows` tab and the
+  duplicate Journey-local diagram are removed because they projected the same
+  authored Steps while silently dropping Steps without a Capability. The named
+  topology view is now **Journey composition**: it explicitly answers the
+  narrower Capability-composition question. Outside visible Domain groupings,
+  Capability nodes use the consistent Capability color rather than inheriting
+  a Domain color that could be mistaken for status.
+- **Capability and Journey Scenarios share one Steps treatment.** Both render
+  the same Step-by-route matrix. Columns use the authored route name and stable
+  order; placed cells show the exact typed Interface → Experience → Screen
+  hierarchy. Step-kind labels explain Actor actions, Product actions, and
+  conditions; Capability labels appear only where they discriminate Journey
+  Steps. Steps without a Context and Context transitions are described in
+  plain language, without exposing internal route ids.
+- **The report navigation rail lists kinds, flat.** Kinds do not nest —
+  instances do — so both Scenario kinds leave the rail and are read on the page
+  for the Capability or Journey that owns them. The Capability and Journey main
+  screens open their collections directly, without a redundant parent/Scenario
+  tab strip. Ten destinations instead of twelve, and no indentation claiming a
+  hierarchy the other eight rows have too.
+- **Collection chrome scales with the collection.** The per-relation filter
+  dropdowns collapse into one control with a chip per *active* filter, and it is
+  not rendered at all below eight entities — seven dropdowns above four Journeys
+  was a wall, not an offer. The card-style switcher is gone; the dense row is
+  the only layout, and it carries the fact that distinguishes an entity from its
+  neighbours (a Screen's scope, a Scenario's parent) where the repeated kind
+  label used to be.
+- Entity tables render the name of a relation the format makes single-valued
+  rather than the count `1`, and drop any column constant across the rows on
+  screen.
+- The bundled skills carry a worked Capability Scenario. The reference every
+  skill reads described `routes`, typed `steps`, and per-route Contexts in
+  prose but showed no Scenario file, leaving the model's most structured
+  artifact to be inferred. The example is single-route, because that is the
+  case where the `routes` requirement is least guessable.
+- The bundled skills name the Product's portable identity keys — `summary`,
+  `category`, `authors`, and `license`. Report hosts read all four, and a model
+  authored without them reaches a Blueprint incomplete.
+- `npm run check` asserts that every entity kind, frontmatter key, and required
+  section named in `spec/format.md` also appears in the canonical skill
+  reference. The reference may be terser than the contract; it may not omit a
+  name, because an agent cannot author a key it was never told about. It found
+  the three missing Product keys above on its first run.
+- A README for the `businesslens/nuxt/theme` layer, which shipped as a public
+  export with no documentation of its palette roles, type scale,
+  `<BusinessLensBrand>` lockup, or icon-family composable.
+- **Folder schema 5 — a breaking change with no compatibility reader.** An
+  entity is compact as `<id>.md` until it owns an asset or typed child
+  collection, then expands to `<id>/<type>.md`. Both shapes derive the same id
+  and cannot coexist. This keeps leaf-heavy collections readable while giving
+  every kind—Screens most of all—a co-located namespace when needed.
+  `product.md` similarly expands to `product/product.md` only when it owns
+  `logo.svg`. Two coexisting shapes, and an expanded folder missing its
+  `<type>.md`, are `lint` errors — neither is a state a correct model passes
+  through. An expanded folder that owns nothing *yet* is a warning instead: the
+  rule still holds, and expansion normalizes the folder back to the compact
+  form, but an author reaches the expanded shape in two steps and the
+  intermediate step is not a defect.
+- **The Interface → Experience → Screen hierarchy nests.** An Experience
+  belongs to exactly one Interface and
+  a Screen to exactly one scope, so the path is the parent relation. An
+  Experience no longer writes `interfaces:`, a Capability Scenario no longer
+  writes `capability:`, a Journey Scenario no longer writes `journey:`, and a
+  Screen no longer writes `availability:`. Reparenting is a `git mv` that reads
+  correctly in a pull request.
+- **Interface, Experience, and Screen ids are qualified** by the path that
+  distinguishes them. Experience and Screen names repeat across Interfaces on purpose: two entities of the same
+  kind sharing a path suffix below their Interface are counterparts — the same
+  thing on two Interfaces. Behavior-tree ids stay bare and globally unique.
+- **Domain is a subject axis, not a capability folder.** It now requires a
+  `## Boundary` section, and only Capability authors `domain:` — a Screen's,
+  Experience's or Journey's Domains are derived through their Capabilities
+  rather than restated where a second copy could disagree.
+- Product Report `schemaVersion` is `10.0.0`, and the catalog media type moves
+  to `version=10`. There is exactly one accepted report version, as before.
+- Scenario documentation moves onto its parent's page. A Scenario is not a
+  top-level entity — it has a mandatory single parent that decides its kind —
+  so Capability Scenarios are documented in `docs/capabilities.md`, Journey
+  Scenarios in `docs/journeys.md`, and the containment rule that separates them
+  in `docs/product-model.md`. The standalone `docs/scenarios.md` is removed.
+- An external system is an Actor only when it **initiates** interaction with
+  the Product, and only then does it arrive through an Interface.
+  Interfaces are inbound by definition; an outbound connection the Product
+  opens to a third party — a polled feed, a payment processor, a mail provider,
+  a model API — is not an Interface and its far side is not an Actor. Model the
+  call inside the Capability that makes it, scope that Capability to the
+  Interfaces where an Actor observes the result, and make its
+  product-significant failure behavior a Capability Scenario. Direction, not
+  ownership, is the axis: the same third party calling the Product back through
+  a webhook is a genuine Actor with a genuine Interface. No entity type, folder
+  schema, parser, or linter behavior changes — `lint` cannot recover direction
+  from the files, so the rule lives in `spec/format.md`, the Product Model
+  docs, and the mapping rubric.
+- The Content Feed Reader Blueprint applies that rule. It drops the
+  `feed-provider` Actor and the `syndicated-feed-integration` Interface;
+  `feed-synchronization` now lives on the Reader-facing Interfaces where its
+  result is seen, carries the RSS specification as a context Reference, and is
+  triggered by a Reader-initiated refresh on the Source list Screen — a trigger
+  the model previously never stated. Its catch-up failure variation no longer
+  contradicts itself about whether the backlog was unchanged or caught up.
+- **Breaking.** `businesslens/nuxt/report-viewer` accepts the canonical
+  `ProductReportV10` directly and owns the complete Product Report projection
+  and topology engine. The lossy `businesslens/report/view-model` export and
+  the former whole-report audition layer are removed. The private,
+  unpublished `report-viewer-lab` remains as an empty boundary for future
+  experiments, while `theme-lab` continues to own background auditions.
+- **Breaking.** Logo, lockup, and favicon selection are no longer theme-lab
+  experiments. The approved mark, wordmark, brand renderer, favicon, and
+  install-icon family now live at canonical paths in `businesslens/nuxt/theme`;
+  `businesslens/theme-lab/variants` exposes background choices only.
+- The Product Report keeps entity identity collision-safe across collections,
+  preserves focus across live recompiles, separates Capability and Journey
+  Scenario readings, shows Screen-to-Journey derivation provenance, renders
+  ordered Journey path lanes, and uses fixed named views instead of a generic
+  cross-kind grouping builder. Mobile navigation is a dedicated drawer.
+- Product Report v10 stores authored supporting H2 sections as ordered
+  `{ heading, content }` records instead of an opaque Markdown string. Lint
+  rejects Journey and Scenario lead prose, duplicate or conflicting structured
+  sections, malformed structured lists, and duplicate values in set-valued
+  relations rather than allowing authored content to disappear or inflate
+  derived relationships.
+- The Content Feed Reader catalog Blueprint now models two actor-facing access
+  boundaries: Reader work and Visitor consumption. Feed collection is an
+  outbound Capability dependency rather than a synthetic Actor or Interface.
+  The model has two Actors, two Interfaces, three Experiences, three Domains,
+  eight Screens, ten Capabilities, twenty-four Capability Scenarios, four
+  Journeys, eight Journey Scenarios, and four Business Rules. Domains group
+  Capabilities on one axis — Sources, Reading, Collections — so no Capability
+  needs its Domain's definition widened to admit it.
+- Both teaching models now demonstrate a Journey that is attempted and not
+  reached. The Blueprint carries two `not-achieved` Journey Scenarios and the
+  golden fixture one, so `result` is an axis with real values rather than a
+  constant, and `failureOnlyCapabilityIds` is exercised against authored
+  content instead of always deriving empty.
+- The Product Report treats Capability Scenarios and Journey Scenarios as
+  separate entity kinds rather than one kind carrying a type flag. They remain
+  contained by their Capability or Journey while preserving their own search
+  results, pages, terminal results, and derived backlinks.
+
+### Fixed
+
+- The release artifact smoke test follows the promoted stable boundaries: it
+  requires the approved icon under `theme`, not an old `theme-lab` audition
+  path, and rejects the retired lossy Report View Model export instead of
+  requiring it. The stale assertions stopped the first `v0.8.0` publish
+  attempts before npm.
+- `package.json` no longer lists `plans/shared-theme-lab.md` among its packaged
+  files. The file was deleted while the entry stayed, and npm drops a missing
+  `files` entry silently, so the packed tarball simply carried no `plans/` at
+  all and nothing reported it.
+- The docs group allowlist no longer permits `Learn from examples`, which no
+  page has used since the feed-reader walkthrough was removed. An allowed group
+  with nothing behind it is a sidebar section the navigation cannot build.
+- Two routes of one Scenario that repeat the same Context place sequence are
+  now a finding in both `lint` and report validation. A route id names one
+  traversal, so a second id over the same sequence claims a lane the Product
+  does not have. The Content Feed Reader Blueprint carried two:
+  `publish-on-mobile` and `unlist-from-mobile`, which never left the web
+  Interface, and could not have — neither Capability declares a mobile context.
+- Entity pages no longer inherit the scroll offset of the collection or entity
+  that opened them, so each reading begins at its own title, identity, and lead.
+- The local viewer resolves the Blueprint logo at `product/logo.svg`, where
+  schema 5 puts it once the Product expands.
+- An unexpected entry in a collection is now an explicit finding. A file nested
+  one level too deep, or saved with the wrong extension, previously vanished
+  from the model with no finding at all.
+- The local viewer's Content-Security-Policy sets `manifest-src`, which was
+  blocking `site.webmanifest`.
+- The Product Report light and dark page surfaces are part of the shared theme
+  again. The warm base, top glow, and paper grain moved from the optional
+  theme-lab audition layer into `businesslens/nuxt/theme`, where the promoted
+  Product Report and the bundled local viewer inherit them without depending on a
+  lab layer.
+- Journey composition no longer implies a Screen is reached from a Step that
+  cannot expose it. A Screen is authored against the whole Journey Scenario, so
+  it now attaches to the last Capability-bearing Step whose Capability declares that
+  Screen and shares an availability context with it — a non-visual integration
+  Step no longer appears to land on a Reader Screen.
+- Journey composition lays ordered Capability-bearing Steps downward with variations side by side. A
+  left-to-right chain was wider than the canvas for a short Journey, so it
+  scaled the whole graph down and left the height unused.
 
 ## [0.7.2] - 2026-08-05
 
@@ -68,10 +495,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `report only` verification mode, an explicit missing-builder handoff, and an
   unchanged-gap stopping rule. Verification findings are re-derived rather than
   persisted in a receipt or ledger.
-- Accepted decisions covering [repository-owned files](./adr/0004-write-nothing-outside-businesslens.md),
-  [unified References](./adr/0008-unified-references-and-portable-reports.md),
-  [non-persisted verification](./adr/0006-verification-is-not-persisted.md),
-  and the [three-skill boundary](./adr/0007-three-skills-and-one-verification-loop.md).
+- Accepted decisions covering repository-owned files, unified References,
+  non-persisted verification, and the three-skill boundary.
 
 ### Changed
 
@@ -271,7 +696,9 @@ Initial public launch of the repository.
   `docs/format.md`.
 - Claude plugin manifest and marketplace entry.
 
-[Unreleased]: https://github.com/businesslens/pdd/compare/v0.7.2...HEAD
+[Unreleased]: https://github.com/businesslens/pdd/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/businesslens/pdd/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/businesslens/pdd/compare/v0.7.2...v0.8.0
 [0.7.2]: https://github.com/businesslens/pdd/compare/v0.7.1...v0.7.2
 [0.7.1]: https://github.com/businesslens/pdd/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/businesslens/pdd/compare/v0.6.0...v0.7.0

package/README.md

@@ -6,7 +6,8 @@
 
 **Product-Driven Development for coding agents.** BusinessLens keeps intended
 product behavior in a Git-tracked `.businesslens/` Product Model: who the
-product serves, what they accomplish, and which rules must remain true.
+product serves, what they accomplish, what it keeps and what changes it, and
+which rules must remain true, including who may act.
 
 The model is Markdown, reviewable in pull requests, and useful without a hosted
 service. `businesslens lint` checks its structure. The `businesslens-verify`
@@ -16,19 +17,19 @@ resolution loop.
 ```text
 .businesslens/
 ├── README.md
-├── product.md
-├── actors/
-├── interfaces/
-├── experiences/
-├── screens/                  # optional product views
-├── domains/                  # optional organization
-├── capabilities/
-├── business-rules/
-├── journeys/<id>/journey.md
-│   └── scenarios/<id>.md
+├── product.md                # or product/product.md beside logo.svg
+├── entities/<id>.md          # or <id>/entity.md with assets; the ones that act carry kind and acts
+├── interfaces/<id>.md        # or <id>/interface.md with screens/ or experiences/
+├── domains/<id>.md           # or <id>/domain.md with assets; optional collection
+├── capabilities/<id>.md      # or <id>/capability.md with scenarios/ or assets
+├── journeys/<id>.md          # or <id>/journey.md with scenarios/ or assets; optional
+├── business-rules/<id>.md    # or <id>/business-rule.md with assets
 └── coverage.md
 ```
 
+Leaf resources stay compact as `<id>.md`. A resource expands to
+`<id>/<type>.md` only when it needs a namespace for assets or child resources.
+
 ## Getting started
 
 Install the skills:
@@ -93,25 +94,61 @@ Catalog contribution stays in the CLI; there is no contribution skill.
 ## Product Model semantics
 
 - `references` optionally attach intent, implementation, or context artifacts
-  to any semantic entity. They are navigation and supporting material, not
+  to any semantic resource. They are navigation and supporting material, not
   proof or verification receipts.
 - `coverage.status` describes model breadth: `draft` while the model itself is
   under review, `partial` with known unmapped areas, and `complete` when the
-  intended product scope is modeled.
+  intended product breadth is modeled.
 - A complete model may contain zero References.
 - A Product may expose several Interfaces—such as web, mobile, CLI, and a
   supported API—without being classified as one of those delivery forms.
-- Experiences are coherent usage contexts across Interfaces; exact
-  Interface–Experience availability says where behavior is promised.
-- Domains are optional Capability groupings, and Journeys may cross them.
-- Screens are optional platform-neutral product views. Screenshots and other
-  visuals remain external References, not model assets or proof.
+- Experiences are optional coherent usage contexts, each belonging to exactly
+  one Interface. Availability is a list of strict Context objects whose
+  `place` is an undivided Interface or an Experience.
+- Domains are optional regions of subject matter. Only a Capability authors
+  `domain:`; every other Domain relation is derived.
+- Screens are optional platform-neutral product views, nested in the Interface
+  or Experience that contains them. Their path supplies their place. Product
+  assets sit beside the resource they describe; anything
+  under `implementation/` describes this realization and stays home.
 - `lint` checks format, required content, relationships, Reference grammar, and
   tracked code-reference paths. `verify` checks meaning against current code.
 
 Every model creation path writes `.businesslens/README.md`. BusinessLens never
 writes target `AGENTS.md`, `CLAUDE.md`, or root README files.
 
+## Where the Product Model is defined
+
+Use these sources in this order:
+
+1. Read the [Product Model overview](./docs/product-model.md) for the mental
+   model and relationship overview.
+2. Use [`spec/format.md`](./spec/format.md) as the normative contract for the
+   authored `.businesslens/` files. It defines every resource type, file shape,
+   relation, and semantic boundary, and changes before parser or linter
+   behavior changes. Its companion [`spec/report.md`](./spec/report.md) is the
+   contract for the serialized Product Report, its portable projection, and
+   expansion.
+3. Use the individual resource type pages under [`docs/`](./docs/) for approachable
+   explanations, examples, and the relevant `lint` findings. They restate the
+   format contract and must not introduce a second definition.
+4. Follow [`src/core/model.ts`](./src/core/model.ts),
+   [`src/core/frontmatter.ts`](./src/core/frontmatter.ts),
+   [`src/core/markdown.ts`](./src/core/markdown.ts), and
+   [`src/commands/lint.ts`](./src/commands/lint.ts) to understand what the CLI
+   parses and enforces today.
+5. Use [`src/core/portable.ts`](./src/core/portable.ts) for the generated Product
+   Report JSON schema and relationship validation, and
+   [`src/commands/export.ts`](./src/commands/export.ts) for the authored-model to
+   report projection.
+
+The installed skills carry self-contained format summaries and semantic
+rubrics so agents can judge concepts that structural lint cannot prove—for
+example, whether something is genuinely a durable Capability or a coherent
+multi-Capability Journey. Those guides must remain consistent with
+`spec/format.md`; they do not supersede it. Viewer backlinks and topology are
+derived report projections, not additional authored relationships.
+
 ## Documentation
 
 - [Introduction](./docs/index.md) · [Installation](./docs/installation.md) ·
@@ -119,11 +156,11 @@ writes target `AGENTS.md`, `CLAUDE.md`, or root README files.
 - Start [from your repo](./docs/from-your-repo.md),
   [from a Blueprint](./docs/from-a-blueprint.md), or
   [from an idea](./docs/from-an-idea.md)
-- [Product Model](./docs/product-model.md) ·
-  [References](./docs/references.md)
+- [Product Model](./docs/product-model.md) · [References](./docs/references.md)
 - [Skills](./docs/skills.md) · [CLI](./docs/cli.md) ·
   [CI/CD](./docs/ci.md)
-- [Format contract](./spec/format.md)
+- [Format contract](./spec/format.md) ·
+  [Report contract](./spec/report.md)
 
 ## Nuxt layers
 
@@ -131,12 +168,14 @@ The package also exposes separately composable Nuxt layers:
 
 - `businesslens/nuxt/report-viewer` renders a Product Report without owning its
   host navigation or page shell.
-- `businesslens/nuxt/theme` provides the stable BusinessLens palette, type, and
-  semantic UI foundation.
+- `businesslens/nuxt/theme` provides the stable BusinessLens palette, type,
+  semantic UI foundation, approved surfaces, logo/wordmark renderer, and
+  browser/install icon family.
 - `businesslens/nuxt/theme-lab` extends that stable theme with the shared,
-  opt-in background and brand experiments used by the landing site and local
-  report viewer. Its ownership and promotion rules are recorded in
-  [`plans/shared-theme-lab.md`](./plans/shared-theme-lab.md).
+  opt-in background experiments used by the landing site and local report
+  viewer. A consumer that does not opt in receives the approved stable
+  presentation from `theme`; a background graduates by moving into `theme`,
+  never by a consumer depending on `theme-lab` in production.
 
 ## Safety
 

package/dist/businesslensThemeLabVariants.d.ts

@@ -14,26 +14,5 @@ declare const BUSINESSLENS_DARK_BACKGROUNDS: BusinessLensBackgroundVariant[];
 declare const BUSINESSLENS_DEFAULT_LIGHT_BACKGROUND = "l4";
 declare const BUSINESSLENS_DEFAULT_DARK_BACKGROUND = "d1";
 declare function findBusinessLensBackground(list: BusinessLensBackgroundVariant[], id: string | null | undefined, fallback: string): BusinessLensBackgroundVariant;
-type BusinessLensLogoDisplay = 'mark' | 'lockup';
-interface BusinessLensLogoVariant {
-  id: string;
-  name: string;
-  tagline: string;
-  /** Basename under `/brand/logo/variants`, without the `-dark` suffix. */
-  file: string;
-}
-interface BusinessLensLockupVariant extends BusinessLensLogoVariant {
-  direction: 'row' | 'column';
-  wordmarkHeight: number;
-  symbolScale: number;
-  gapRatio: number;
-}
-declare const BUSINESSLENS_MARK_VARIANTS: BusinessLensLogoVariant[];
-declare const BUSINESSLENS_LOCKUP_VARIANTS: BusinessLensLockupVariant[];
-declare const BUSINESSLENS_DEFAULT_MARK: string;
-declare const BUSINESSLENS_DEFAULT_LOCKUP = "k3";
-declare const BUSINESSLENS_DEFAULT_LOGO_DISPLAY: BusinessLensLogoDisplay;
-declare function businessLensLogoSrc(variant: BusinessLensLogoVariant, dark?: boolean): string;
-declare function findBusinessLensLogo<T extends BusinessLensLogoVariant>(list: T[], id: string | null | undefined, fallback: string): T;
 //#endregion
-export { BUSINESSLENS_DARK_BACKGROUNDS, BUSINESSLENS_DEFAULT_DARK_BACKGROUND, BUSINESSLENS_DEFAULT_LIGHT_BACKGROUND, BUSINESSLENS_DEFAULT_LOCKUP, BUSINESSLENS_DEFAULT_LOGO_DISPLAY, BUSINESSLENS_DEFAULT_MARK, BUSINESSLENS_LIGHT_BACKGROUNDS, BUSINESSLENS_LOCKUP_VARIANTS, BUSINESSLENS_MARK_VARIANTS, BusinessLensBackgroundVariant, BusinessLensLockupVariant, BusinessLensLogoDisplay, BusinessLensLogoVariant, businessLensLogoSrc, findBusinessLensBackground, findBusinessLensLogo };
+export { BUSINESSLENS_DARK_BACKGROUNDS, BUSINESSLENS_DEFAULT_DARK_BACKGROUND, BUSINESSLENS_DEFAULT_LIGHT_BACKGROUND, BUSINESSLENS_LIGHT_BACKGROUNDS, BusinessLensBackgroundVariant, findBusinessLensBackground };