hyperpolymath · hyperpolymath · Jan 9, 2026 · Jan 9, 2026
diff --git a/.machine_readable/META.scm b/.machine_readable/META.scm
@@ -3,15 +3,45 @@
 ;; Media-Type: application/meta+scheme
 
 (meta
-  (architecture-decisions ())
+  (architecture-decisions
+    ("ADR-001" "Hospital mental model"
+      "Use hospital metaphor (Ward/ER/OR/Records) for UX to reduce user anxiety and provide clear navigation")
+    ("ADR-002" "Umbrella + satellite architecture"
+      "Umbrella repo coordinates satellites for separation of concerns; implementations in dedicated repos")
+    ("ADR-003" "Evidence-first, no fearware"
+      "Show measurements not hype; no inflated counts or fake urgency; trust through transparency")
+    ("ADR-004" "Plan-Apply-Undo-Receipt pattern"
+      "All mutations require explicit approval, produce receipts, and support undo where possible")
+    ("ADR-005" "Local-first by default"
+      "Privacy controls visible and simple; local-only mode fully supported without degradation"))
 
   (development-practices
-    (code-style ())
+    (code-style
+      ("AsciiDoc for documentation")
+      ("Guile Scheme for machine-readable state")
+      ("No TypeScript/Python per RSR language policy")
+      ("ReScript for any future UI components"))
     (security
-      (principle "Defense in depth"))
-    (testing ())
+      (principle "Defense in depth")
+      (principle "No hardcoded secrets")
+      (principle "SHA-pinned dependencies")
+      (principle "SPDX license headers required"))
+    (testing
+      ("SCM file validation via Guile")
+      ("RSR compliance validation")
+      ("Documentation coverage checks"))
     (versioning "SemVer")
-    (documentation "AsciiDoc")
-    (branching "main for stable"))
+    (documentation "AsciiDoc primary, Markdown for GitHub compatibility")
+    (branching "main for stable, feature branches for development"))
 
-  (design-rationale ()))
+  (design-rationale
+    ("Hospital model reduces anxiety"
+      "System tools often scare users; hospital metaphor communicates safety, consent, and expert help")
+    ("Profiles over one-size-fits-all"
+      "Different users (child/general/dev/tech) need different intrusiveness and detail levels")
+    ("HAT roles for guidance"
+      "Role-based helpers (Coordinator/Information/Risk/Optimisation) provide focused, non-overlapping advice")
+    ("Receipts build trust"
+      "Every action produces a receipt; users can review, share, and undo; transparency over magic")
+    ("Satellite repos for modularity"
+      "Each department (Ward/ER/OR/Records) can evolve independently with clear contracts")))
diff --git a/.machine_readable/STATE.scm b/.machine_readable/STATE.scm
@@ -4,36 +4,68 @@
 
 (state
   (metadata
-    (version "0.0.1")
+    (version "0.1.0")
     (schema-version "1.0")
     (created "2026-01-03")
-    (updated "2026-01-03")
+    (updated "2026-01-09")
     (project "ambientops")
     (repo "github.com/hyperpolymath/ambientops"))
 
   (project-context
-    (name "ambientops")
-    (tagline "")
-    (tech-stack ()))
+    (name "AmbientOps")
+    (tagline "Cross-platform system tools for everyday users - trustworthy help without fearware")
+    (tech-stack
+      ("AsciiDoc" "documentation")
+      ("Guile Scheme" "machine-readable state files")
+      ("Justfile" "task automation")))
 
   (current-position
-    (phase "initial")
-    (overall-completion 0)
-    (components ())
-    (working-features ()))
+    (phase "bootstrap")
+    (overall-completion 10)
+    (components
+      ("umbrella-repo" 90 "Docs, manifest, packaging glue")
+      ("hospital-model" 80 "UX model documented")
+      ("ecosystem-manifest" 50 "Structure defined, needs satellite repos")
+      ("contracts" 0 "Not started - Phase 1"))
+    (working-features
+      ("Documentation site structure")
+      ("Hospital model specification")
+      ("Ecosystem manifest format")
+      ("RSR compliance structure")))
 
   (route-to-mvp
-    (milestones ()))
+    (milestones
+      ("Phase 0 - Bootstrap" "in-progress"
+        "Umbrella repo, hospital model docs, ecosystem manifest, trust principles")
+      ("Phase 1 - Contracts" "planned"
+        "System Weather schema, evidence envelope, receipt schema, deep-link format")
+      ("Phase 2 - Ward MVP" "planned"
+        "Tray app, HAT roles, theme packs, local-only mode")
+      ("Phase 3 - Emergency Room MVP" "planned"
+        "Incident bundle, safety posture, handoff flows")
+      ("Phase 4 - Operating Room MVP" "planned"
+        "Scan/Plan/Apply/Undo/Receipt flow, safe pack v0.1")
+      ("Phase 5 - Ecosystem polish" "planned"
+        "Cross-platform packaging, technician packs, adapters")))
 
   (blockers-and-issues
     (critical)
-    (high)
-    (medium)
+    (high
+      ("Need to create satellite repos for Ward, ER, OR, Records"))
+    (medium
+      ("system-tools-contracts repo not yet created"))
     (low))
 
   (critical-next-actions
-    (immediate)
-    (this-week)
-    (this-month))
+    (immediate
+      ("Complete umbrella repo documentation")
+      ("Define contracts for satellite repos"))
+    (this-week
+      ("Create system-tools-contracts repo")
+      ("Draft System Weather payload schema"))
+    (this-month
+      ("Begin Ward MVP implementation")
+      ("Establish satellite repo structure")))
 
-  (session-history ()))
+  (session-history
+    ("2026-01-09" "Resolved all TODOs and stubs in umbrella repo")))
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -1,28 +1,8 @@
 # Code of Conduct
 
-<!-- 
-============================================================================
-TEMPLATE INSTRUCTIONS (delete this block before publishing)
-============================================================================
-Replace all {{PLACEHOLDER}} values:
-  {{PROJECT_NAME}}     - Your project name
-  {{OWNER}}            - GitHub/GitLab username or org
-  {{REPO}}             - Repository name
-  {{CONDUCT_EMAIL}}    - Email for conduct reports
-  {{CONDUCT_TEAM}}     - Name of conduct team/committee
-  {{RESPONSE_TIME}}    - Initial response SLA (e.g., 48 hours)
-  {{CURRENT_YEAR}}     - Current year
-
-Review and customise:
-- Adjust enforcement ladder for your community size
-- Add/remove examples based on your context
-- Ensure contact methods work for your team
-============================================================================
--->
-
 ## Our Pledge
 
-We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation.
+We as members, contributors, and leaders pledge to make participation in AmbientOps a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation.
 
 We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
 
@@ -136,7 +116,7 @@ If you experience or witness unacceptable behaviour, or have any other concerns,
 
 | Method | Details | Best For |
 |--------|---------|----------|
-| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters |
+| **GitHub** | Contact @hyperpolymath via GitHub | Detailed reports, sensitive matters |
 | **Private Message** | Contact any maintainer directly | Quick questions, minor issues |
 | **Anonymous Form** | [Link to form if available] | When you need anonymity |
 
@@ -152,8 +132,8 @@ If you experience or witness unacceptable behaviour, or have any other concerns,
 
 **What Happens Next**
 
-1. You will receive acknowledgment within **{{RESPONSE_TIME}}**
-2. The {{CONDUCT_TEAM}} will review the report
+1. You will receive acknowledgment within **48 hours**
+2. The AmbientOps Maintainers will review the report
 3. We may ask for additional information
 4. We will determine appropriate action
 5. We will inform you of the outcome (respecting others' privacy)
@@ -169,7 +149,7 @@ All reports will be handled with discretion:
 
 ### Conflicts of Interest
 
-If a {{CONDUCT_TEAM}} member is involved in an incident:
+If a AmbientOps Maintainers member is involved in an incident:
 
 - They will recuse themselves from the process
 - Another maintainer or external party will handle the report
@@ -179,7 +159,7 @@ If a {{CONDUCT_TEAM}} member is involved in an incident:
 
 ## Enforcement Guidelines
 
-The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences:
+The AmbientOps Maintainers will follow these guidelines in determining consequences:
 
 ### 1. Correction
 
@@ -231,13 +211,13 @@ For contributors with elevated access (Perimeter 2 or 1):
 If you believe an enforcement decision was made in error:
 
 1. **Wait 7 days** after the decision (cooling-off period)
-2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]"
+2. **Contact** the maintainers via GitHub with subject line "Appeal: [Original Report ID]"
 3. **Explain** why you believe the decision should be reconsidered
 4. **Provide** any new information not previously available
 
 **Appeals Process**
 
-- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original
+- Appeals are reviewed by a different AmbientOps Maintainers member than the original
 - You will receive a response within 14 days
 - The appeals decision is final
 - You may only appeal once per incident
@@ -310,8 +290,8 @@ We thank these communities for their leadership in creating welcoming spaces.
 
 If you have questions about this Code of Conduct:
 
-- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions)
-- Email {{CONDUCT_EMAIL}} (for private questions)
+- Open a [Discussion](https://github.com/hyperpolymath/ambientops/discussions) (for general questions)
+- Contact the maintainers via GitHub (for private questions)
 - Contact any maintainer directly
 
 ---
@@ -324,4 +304,4 @@ We're all here because we care about this project. Let's make it a place where e
 
 ---
 
-<sub>Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1</sub>
+<sub>Last updated: 2026 · Based on Contributor Covenant 2.1</sub>
diff --git a/ECOSYSTEM.scm b/ECOSYSTEM.scm
@@ -4,10 +4,25 @@
 (ecosystem
   ((version . "1.0.0")
    (name . "ambientops")
-   (type . "application")
-   (purpose . "image:https://img.shields.io/badge/License-AGPL--3.0--or--later-blue.svg[AGPL-3.0,link="https://www.gnu.org/licenses/agpl-3.0"]")
-   (position-in-ecosystem . "supporting")
+   (type . "umbrella-application")
+   (purpose . "Cross-platform system tools ecosystem for everyday users")
+   (position-in-ecosystem . "coordinator")
    (related-projects
-     ((palimpsest-license . "license-framework")))
-   (what-this-is . ("image:https://img.shields.io/badge/License-AGPL--3.0--or--later-blue.svg[AGPL-3.0,link="https://www.gnu.org/licenses/agpl-3.0"]"))
-   (what-this-is-not . ())))
+     ((ops-glance . "Ward UI - tray/ambient system weather")
+      (emergency-button . "Emergency Room - panic-safe intake")
+      (operating-room . "Operating Room - planned procedures engine")
+      (juliadashboard . "Observability dashboard")
+      (personal-sysadmin . "Clinician workflows")
+      (hybrid-automation-router . "Policy-gated execution")
+      (feedback-a-tron . "Referrals/discharge notes")
+      (system-tools-contracts . "Shared schemas and contracts")
+      (palimpsest-license . "License framework")))
+   (what-this-is
+     ("Umbrella repository for AmbientOps ecosystem")
+     ("Documentation and UX model (hospital metaphor)")
+     ("Ecosystem manifest and coordination")
+     ("Packaging glue for installers"))
+   (what-this-is-not
+     ("Not the implementation of Ward/ER/OR - those live in satellite repos")
+     ("Not a monolithic application")
+     ("Not fearware or nagware"))))
diff --git a/PLAYBOOK.scm b/PLAYBOOK.scm
@@ -1,11 +1,46 @@
 ;; SPDX-License-Identifier: MPL-2.0
-;; PLAYBOOK.scm - Operational runbook
+;; PLAYBOOK.scm - Operational runbook for AmbientOps umbrella repo
 
 (define playbook
   `((version . "1.0.0")
     (procedures
-      ((build . ())
-       (test . ())
-       (deploy . ())))
-    (alerts . ())
-    (contacts . ())))
+      ((build
+         (description . "Build documentation from AsciiDoc sources")
+         (command . "just build")
+         (prerequisites . ("asciidoctor installed"))
+         (output . "dist/html/"))
+       (test
+         (description . "Validate RSR compliance and SCM file syntax")
+         (command . "just test")
+         (prerequisites . ("guile installed"))
+         (checks . ("RSR compliance" "STATE.scm syntax" "All SCM files")))
+       (deploy
+         (description . "Deploy documentation to GitHub Pages")
+         (command . "just build-release && git subtree push --prefix dist/html origin gh-pages")
+         (prerequisites . ("asciidoctor" "asciidoctor-pdf" "git"))
+         (notes . "Ensure dist/html is built before pushing"))
+       (validate
+         (description . "Run full validation suite")
+         (command . "just validate")
+         (checks . ("RSR files" "STATE.scm" "All SCM files")))
+       (release
+         (description . "Prepare a new release")
+         (steps . ("Update version in STATE.scm"
+                   "Update CHANGELOG"
+                   "Run just validate"
+                   "Tag release: git tag -a vX.Y.Z"
+                   "Push: git push --tags")))))
+    (alerts
+      ((scm-parse-failure
+         (severity . "high")
+         (description . "SCM file failed to parse")
+         (action . "Check syntax with: guile -c '(primitive-load \"FILE.scm\")'"))
+       (rsr-compliance-failure
+         (severity . "medium")
+         (description . "RSR compliance check failed")
+         (action . "Run 'just validate-rsr' and fix missing files"))))
+    (contacts
+      ((maintainer
+         (name . "Jonathan D.A. Jewell")
+         (github . "@hyperpolymath")
+         (role . "Lead Maintainer"))))))