Garden OS
A local-first raised-bed planning and story system. Root tools run entirely in
the browser; Story Mode can also use an optional signed authority service while
retaining local offline persistence.
Problem Statement
Most garden planners answer "where should I plant this?" with weak reasoning transparency.
Garden OS focuses on explainable decisions:
- sun fit
- support fit
- shade tolerance
- access fit
- seasonal fit
- structural bonus
- adjacency effects
The system also highlights the limiting factor so users can make high-leverage changes quickly.
Features
- Active v5 Beds What-If trials with zero persistent writes before Apply
- Cross-bed A/B experiments with immutable baselines, dated observations, and read-only Planner summaries
- Explainable scoring panel in Inspect tab
- Limiting-factor detection for each selected crop/cell
- Adjacency analysis (companion/conflict/water mismatch)
- Workspace export/import with
.gos.json
- Export-only reasoned summaries for temporal context, multi-bed comparison, companion findings, and active-cell explanation
- Canonical data contract in
gos-schema.json
- Light-default, user-selectable light/dark themes shared across public routes
- Installable PWA with verified first-visit registration and offline reload
- Story Mode, Free Play, and Story Planner with explicit persistence boundaries
Quick Start
- Clone the repo.
- Open
index.html in a modern browser.
- Launch the active v5 surfaces:
garden-painting.html for Beds and
garden-planner-v5.html for the seasonal Planner.
The current root surfaces can run without install, build, or runtime services.
That is a shipping mode, not a permanent architecture rule.
Usage Example
- Select a crop in the palette.
- Paint cells in the bed.
- Open Inspect tab on a planted cell.
- Read the
Why this score? breakdown.
- Move the crop based on limiting-factor diagnostics.
- Export workspace to
.gos.json for backup or sharing.
Structure
garden-os/
├── index.html # Canonical Home redirect
├── index-v5.html # Current product Home implementation
├── garden-painting.html # Active v5 Beds editor and experiments
├── garden-planner-v5.html # Active v5 seasonal planner
├── garden-doctor-v5.html # Active symptom triage
├── journal.html # Local-first garden journal
├── how-it-thinks-v5.html # Plain-English scoring walkthrough
├── garden-theme.js # Shared light/dark preference + visible toggle
├── garden-pwa.js # Shared service-worker registration
├── gos-experiments.js # Cross-bed experiment contract/store
├── garden-cage-build-guide.html # Cage construction guide
├── garden-cage-ops-guide.html # Operations and maintenance guide
├── scoring-map.html # Scoring architecture reference
├── scoring-visualizer.html # Scoring debugger
├── system-topology.html # Ecosystem topology map
├── brand-guide.html # Brand token and component reference
├── specs/ # Data schemas and reference JSON
├── docs/ # Design docs, audits, roadmaps
├── AGENTS.md # Agent instructions (issue tracker deprecated; see docs/UI_ISSUES_TABLE.html)
├── CLAUDE.md # Architecture constraints
└── README.md # This file
Deployment
Tech
- HTML5, CSS3, JavaScript, and vendored React for active v5 surfaces
- localStorage/file persistence for root tools; IndexedDB/local fallback plus an
optional signed authority API for Story Mode
- JSON Schema for contract validation
- Offline-capable (no network required except Google Fonts)
Smoke Checklist
Roadmap
- Recover the printable garden plan on the active v5 bed contract
- Re-plan the live weather coach with explicit privacy, cache, offline, CSP, and
permission behavior
- Close the remaining Story Mode touch-drag and window-SFX backlog items
Links
Conventions
This project follows the shared naming conventions in 30-shared-resources/shared-standards/NAMING_CONVENTIONS.md.
License
MIT (project-level convention).
