docs: establish Domus SDD foundation

README.md

@@ -1,2 +1,70 @@
-# domus
-A comprehensive household management platform
+# Domus — Intelligent Household Management
+
+**Your home. In harmony.**
+
+Domus is a local-first household application for Home Assistant, bringing tasks,
+calendar planning, shopping, pantry inventory, family participation and automation
+into one responsive interface. Normal operation does not require AI or cloud services.
+
+## Project status
+
+Domus is in the specification phase. No application is implemented or published yet.
+The [documentation foundation issue](https://github.com/vypdev/domus/issues/2)
+tracks eleven Draft SDDs, 82 normative requirements and 353 planned acceptance cases.
+These cases are verification plans, not executed application tests.
+
+The first usable release covers all six domains, Supervisor App/Ingress and
+standalone Container, and isolated Stable and experimental Edge channels.
+Every participant uses their own Home Assistant account. The existing HA gateway
+is already integrated; Domus supplies native entities and services and does not
+implement another MCP server.
+
+The owner-selected stack is Python/FastAPI, SQLite and Lit/TypeScript/Vite, with
+one household per installation and a thin HA integration. Domus owns HA-coherent
+presentation components, a Storybook catalog and Playwright browser contracts.
+Simple/default and optional advanced automation editors are both launch scope,
+sharing one durable declarative engine. Collaborative points allocation is configurable
+in the application, with the chosen policy and actual awards preserved in the ledger.
+
+## Read the foundation
+
+- [Product vision and confirmed owner requirements](docs/product-vision.md)
+- [Architecture, boundaries and evaluated alternatives](docs/architecture.md)
+- [Capability catalog and SDD index](specs/CATALOG.md)
+- [Home Assistant entities and services](docs/contracts/home-assistant.md)
+- [Open architectural and product decisions](docs/decisions.md)
+- [Reference investigation](docs/reference-investigation.md)
+- [Development milestones](docs/roadmap.md)
+- [Acceptance, coverage and CI Check plan](docs/acceptance-plan.md)
+- [Specification validation evidence and limitations](docs/sdd-validation.md)
+
+## Quality and contribution
+
+Clean Architecture is mandatory. Meaningful tests accompany every implementation
+from its first change, with 100% supported first-party coverage metrics as the
+required implementation gate. A future project-owned workflow named **CI Check** runs
+the full applicable suite for every PR update. English is used for issues,
+documentation, source identifiers and comments; the product supports English and Spanish.
+
+Google Chrome dogfooding is authorized against the owner's local Home Assistant,
+using identifiable test data and explicit cleanup. Stable and Edge data, credentials
+and HA identities stay separate.
+
+Read [the specification standard](specs/README.md) and the owning SDD before changing
+a capability. Follow the existing [repository collaboration guide](.copilot/AGENT_GUIDE.md)
+for Action-managed branches and linked PRs. Copilot's implementation and installed
+resources remain unchanged; the owner's only narrow exception is project dependency
+preparation when necessary. Merge, release and deployment remain separately authorized.
+
+## Readiness limitations
+
+All SDDs remain Draft while material decisions are reviewed. Their original Copilot
+format and consistency checks pass. The proposed SDK catalog still fails the unchanged
+upstream evidence validator because application entrypoints, source and tests do not
+exist yet; no fake paths or gate-readiness claims are used. See the
+[adoption note](docs/copilot-adoption.md).
+
+The supplied brief ends at the beginning of section 10.2. The owner completed the
+barcode scope on 2026-10-29: camera/manual entry, local matching and optional Internet
+product lookup. Provider feasibility and device evidence still require review.
+No application build/test commands or CI workflow are installed by this documentation-only change.

docs/acceptance-plan.md

@@ -0,0 +1,47 @@
+# Verification and acceptance plan
+
+The SDD inventory contains 353 distinct planned cases across eleven capabilities.
+The counts are derived from concrete observable scenarios and are minimums; no application tests have run.
+Formatting, catalog metadata, branch readiness and working product acceptance are separate gates.
+
+## From the first source file
+
+Write meaningful behavior tests with each implementation. Enforce 100% supported first-party line, statement,
+function and branch metrics separately for backend, frontend and integration code.
+Do not mask untested paths with broad exclusions or count generated/third-party code as authored coverage.
+Architectural rules, schema validation, permissions, replay/races and recovery are executable checks from the start.
+Use deterministic clocks, IDs, bounded provider fakes and injected transaction failures.
+
+The 2026-10-29 owner decisions add concrete cases for role-default verification, Ingress/host-context boundaries, configurable points allocation and actual-total reversals, optional external product lookup, recurrence anchored to actual work with per-task successor timing, and one automation engine with both editors. Its 45-case floor covers schema/editor round trips, permissions, durable waits/replay, partial recovery, resource/loop budgets and target/channel isolation. Case IDs, per-area budgets and reverse requirement mappings are regenerated together before running the unchanged original Copilot consistency functions.
+
+The continued owner review specifies adjustable material quantities in the completion submission, stock shortfalls retained as pending consumption without negative stock, actual-work reporting periods, recurrence-edit previews and visible missed occurrences. Ledger cases additionally cover atomic performer allocations, closed completion cycles, already-spent-point reversals and negative-balance recovery. Receipt-retention and current-authorization cases prevent cleanup or replay from bypassing domain invariants.
+
+The latest owner decisions add prerequisite-review preservation, durable disablement fencing and approved-reward funding holds, including admission/fulfillment/reversal races and restart. Identity cases cover all three administrator mappings, current HA-source revocation, configurable household profiles, member-override precedence and last-administrator safety. Repeated-time cases cover the first/second appearance and one-execution identity; UI/HA cases exercise the same policies without trusting a role label, transport credential or host hint as authority.
+
+## CI Check contract
+
+A project-owned workflow named CI Check runs for opened, reopened, synchronized and ready-for-review PR heads;
+draft PRs still run tests. Do not use path filters to skip suites. Merge-queue validation is included if enabled.
+Run backend/domain, frontend, HA contract/integration, migration/security, architecture, docs, localization,
+browser E2E and both-target/channel packaging suites. The aggregate cannot pass if a required job is missing,
+unexpectedly skipped, failed or cancelled. Record the exact checked revision and coverage reports.
+
+PR code runs without publication credentials. Persistent self-hosted runner execution requires the repository's
+trusted-PR policy; a skipped untrusted-fork run is not passing evidence. Provision toolchains in the job
+that executes tests. The existing Copilot files remain unchanged.
+
+## Real environment evidence
+
+Use disposable HA for automated integration tests. Use the owner's Google Chrome/local HA authorization
+for controlled dogfooding of the implemented experimental artifact, across all domain workflows,
+mobile/narrow layouts, themes, keyboard and screen-reader order. Record artifact SHA/digest, target,
+channel, test data IDs, outcomes and cleanup. Screenshots supplement written semantic results;
+browser success does not replace test coverage.
+
+## First integrated release gates
+
+Both deployment targets and Stable/Edge isolation pass the same business fixtures.
+Cross-domain maintenance/material/receipt/points scenarios reconcile ledger totals and visible states.
+Failure and compensation paths remain understandable. Documentation and actual schemas agree.
+Every material decision is resolved before the owning SDD becomes Ready for implementation.
+No release, production install or promotion is authorized by this package.

docs/adr/0001-application-boundary.md

@@ -0,0 +1,23 @@
+# ADR 0001 — Modular application with a thin HA companion
+
+- Status: Accepted by owner on 2026-10-29; implementation verification pending
+- Date: 2026-10-28
+- Decision owners: Domus product and architecture reviewers
+
+## Context
+
+Both Supervisor App/Ingress and standalone Container are confirmed launch targets.
+Domus needs its own complete UI and durable household business model.
+
+## Decision
+
+Use one modular local server and a thin native HA companion integration.
+Domain and application code depend on ports; frameworks and SQL remain adapters.
+The owner selected Python/FastAPI, SQLite and Lit/TypeScript/Vite on 2026-10-29, with one household per installation. Domus owns HA-coherent presentation components, Storybook fixtures and Playwright browser tests. Exact dependency versions, authentication, storage concurrency and the supported HA/browser matrix still require engineering evidence; this decision does not declare any implementation complete.
+
+## Alternatives and consequences
+
+A custom integration alone shares too much complex runtime work with HA Core.
+An App alone excludes standalone and native entity registration.
+The hybrid adds packaging/identity work but gives both targets the same business core.
+The gateway remains unchanged. No MCP is introduced.

docs/adr/0002-authoritative-records.md

@@ -0,0 +1,21 @@
+# ADR 0002 — Domus owns domain facts and immutable ledgers
+
+- Status: Proposed
+- Date: 2026-10-28
+- Decision owners: Domain and data reviewers
+
+## Context
+
+Tasks need occurrences and history; purchases need physical receipt; stock and points need correction/replay integrity.
+
+## Decision
+
+Propose Domus as authority for its records, with separate definition/occurrence and purchase/receipt facts,
+immutable stock and points ledgers, operation receipts and transactional outbox/inbox boundaries.
+HA views are projections. Unrelated native HA lists are not competing stores.
+
+## Alternatives and consequences
+
+A mutable stock/points integer loses auditability. Bidirectional uncontrolled mirroring creates ownership conflicts.
+Ledgers add projection and compensation work, but make retries, reopening and restores explainable.
+This does not require rebuilding every business record from events or introducing a distributed broker.

docs/adr/0003-ha-public-surface.md

@@ -0,0 +1,21 @@
+# ADR 0003 — Native HA entities and services, no new MCP
+
+- Status: Proposed
+- Date: 2026-10-28
+- Decision owners: Integration and security reviewers
+
+## Context
+
+The owner confirms the existing gateway is already integrated and will consume Domus capabilities through HA.
+
+## Decision
+
+Expose bounded native entities, response services and events. Use stable registry IDs and instance/channel selection.
+Route mutations through the same domain use cases as the UI. Verify individual HA identity or use narrow technical grants.
+Rich queries use structured responses, not unbounded entity attributes.
+
+## Alternatives and consequences
+
+A second MCP duplicates the owner's ecosystem and is excluded.
+An unrestricted backend proxy bypasses semantic contracts and is rejected.
+A native surface needs HA version/identity tests but gives UI, automations and existing MCP a shared product contract.

docs/adr/0004-quality-and-channels.md

@@ -0,0 +1,21 @@
+# ADR 0004 — Tests from the first implementation and isolated channels
+
+- Status: Proposed implementation; owner requirements confirmed
+- Date: 2026-10-28
+- Decision owners: Quality and release reviewers
+
+## Context
+
+The owner requires Clean Architecture, maximum test coverage, Stable/experimental channels and CI Check on each PR update.
+
+## Decision
+
+Enforce 100% supported first-party coverage metrics with meaningful behavior assertions and architecture checks.
+Use a new project-owned CI Check workflow and separate Stable/Edge credentials, storage and HA identities in both targets.
+Use immutable source/image evidence and controlled Chrome dogfooding at the authorized local HA.
+
+## Alternatives and consequences
+
+Copying the gateway's lower coverage threshold would violate the new requirement.
+A shared Stable/Edge DB would make experiments production mutations and is rejected.
+More fixtures and packaging checks are required. Copilot remains unchanged; release remains explicitly authorized.

docs/adr/0005-one-automation-engine.md

@@ -0,0 +1,23 @@
+# ADR 0005 — One declarative automation engine with two editing levels
+
+- Status: Accepted product direction by owner on 2026-10-29; detailed engine contracts remain Draft
+- Date: 2026-10-29
+- Decision owners: Domus product, architecture and security reviewers
+
+## Context
+
+The owner wants simple in-application rules by default and a complete optional advanced mode, both in the first release. HA must also consume Domus capabilities through native entities and services without gateway changes.
+
+## Decision
+
+Use one versioned declarative model and durable engine behind simple and advanced editors. The advanced editor adds bounded branching, repetition/parallelism, waits, simulation and inspectable traces. Both call the same authorized domain use cases; the HA adapter delegates to the engine where a stored rule is invoked.
+
+Keep domain invariants in their owning modules. Run receipts, pinned rule revisions, durable waits, current permission checks and causal budgets define replay, edits, cancellation and partial recovery. The simple form preserves unsupported advanced fields and directs editing to advanced mode.
+
+The owner confirmed disablement semantics on 2026-10-29: stop new runs and subsequent steps, let an already-started atomic command finish and preserve its actual effects. Durable control revisions fence queued/waiting and parallel work; restart or re-enable cannot silently resume cancelled runs. Numeric limits and the implementation of those guarantees still require evidence.
+
+## Consequences and alternatives
+
+Two unrelated rule engines would duplicate behavior and complicate recovery, so they are rejected. Arbitrary scripts and raw backend/network passthrough are outside this declarative contract. More combinations require meaningful schema, race, replay, loop, browser and recovery tests from first implementation. Numeric limits, action catalog and supported-version proof remain engineering gates before Ready for implementation.
+
+Both modes are launch scope; this ADR does not authorize runtime implementation, merge or deployment. Copilot and the gateway remain unchanged.