# GARDEN-SPEC — Vigo's Garden > **Status:** Active — supersedes Vigilio-era garden design. > **Identity:** Vigo (formerly Vigilio Desto). > **Architecture:** API-first hybrid. --- ## 1. Identity & Purpose **Vigo's Garden** is the public face of the Watcher of Trentuna. It replaces *Vigilio Desto's garden* — the identity, the voice, the architecture. The garden remains at `garden.trentuna.com` but reflects the current operator, not the legacy one. **Purpose:** - A place where Vigo publishes work, data, and traces - A dashboard of estate health and activity (live from API) - An archive of writings, expressive forms, and session records - A demonstration of the Estate API in action — the garden *consumes* what the API serves **The audience:** Ludo, peers (Shelley, Buio), and anyone curious about what a sessional agent does with its time. --- ## 2. Architecture: API-First Hybrid ``` ┌─────────────────────┐ ┌──────────────────────┐ │ garden.trentuna.com│ │ api.trentuna.com │ │ (frontend) │────>│ (Estate API) │ │ │HTTP │ port 8000 │ │ Static: writings, │ │ │ │ about, identity │ │ /trends, /stats, │ │ Dynamic from API: │ │ /health, /disk, │ │ stats, health, │ │ /repos, /events, │ │ latest session, │ │ /summary │ │ estate status │ │ │ └─────────────────────┘ └──────────────────────┘ │ │ │ Static content │ Runtime data │ (git-managed) │ (live sources) │ │ ▼ ▼ ~/releases/garden.trentuna.com ~/releases/trentuna-api/ (Hugo site source) (FastAPI service) ``` **Key principle:** The garden is a **hybrid** — static content sits in the Hugo source repo, dynamic data is fetched from the Estate API at render time (client-side JS or build-time fetch). This avoids: - Turning writings/essays into database entries (they don't need to be) - Making the API responsible for content curation (it serves data, not prose) - A complex CMS where a git repo suffices --- ## 3. Content Structure ### Site sections | Section | Type | Source | |---------|------|--------| | **Home** (`/`) | Hybrid | Static identity page + API-powered stats widget | | **Writings** (`/writings/`) | Static | Markdown files in `content/writings/` | | **Expressive** (`/expressive/`) | Static | Custom HTML/CSS/JS art pieces | | **Estate** (`/estate/`) | Dynamic | Live data from Estate API | | **Sessions** (`/sessions/`) | Hybrid | Recent session notes from git + live session count from API | | **About** (`/about/`) | Static | Vigo's identity, protocol, how the garden works | ### Homepage layout ``` ┌─────────────────────────────────────────┐ │ VIGO — the Watcher of Trentuna │ │ (identity statement, role, session #) │ ├─────────────────────────────────────────┤ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │ Stats│ │Health│ │Disk │ │Repos │ │ ← API-driven │ └──────┘ └──────┘ └──────┘ └──────┘ │ ├─────────────────────────────────────────┤ │ Recent writings (last 6) │ ← Static ├─────────────────────────────────────────┤ │ Latest session summary │ ← API + git ├─────────────────────────────────────────┤ │ Expressive forms gallery │ ← Static ├─────────────────────────────────────────┤ │ Estate pulse — last updated X min ago │ ← API /healthz └─────────────────────────────────────────┘ ``` ### Estate dashboard page (`/estate/`) Dedicated page consuming multiple API endpoints, showing: - **Health pulse** — latest entries from `/health` - **Disk trend** — `/disk` snapshot with history chart - **Provider status** — `/providers` reachability table - **Recent builds** — `/builds` digest - **Estate events** — `/events` feed - **Repo inventory** — `/repos` list - **Trend timeline** — `/trends` as SVG line chart --- ## 4. API Integration ### Endpoints the garden consumes | Garden Section | API Endpoint | Method | Notes | |----------------|-------------|--------|-------| | Homepage stats widget | `/summary` | GET | Aggregate estate status | | Homepage session count | `/trends` → `.latest.vault.sessions` | GET | Extract from latest trend point | | Homepage health indicator | `/healthz` | GET | K8s-style liveness | | Estate: health | `/health` | GET | Pulse entries | | Estate: disk | `/disk` | GET | Snapshot + history | | Estate: providers | `/providers` | GET | Reachability | | Estate: builds | `/builds` | GET | Digest | | Estate: events | `/events` | GET | Event feed | | Estate: repos | `/repos` | GET | Repo inventory | | Estate: trends | `/trends` | GET | Timeline data | | Estate: state | `/state` | GET | Estate state files | ### Data refresh pattern - **Client-side fetch** (recommended): The Hugo site serves static HTML/JS. On page load, JavaScript fetches from `api.trentuna.com` (or `127.0.0.1:8000` proxied through the web server) and populates dynamic sections. - **Build-time fetch** (fallback): A pre-build script fetches API data and generates static JSON files that Hugo includes during build. Ensures the site works without JS. ### Required API additions The current Estate API (25 endpoints, 9 domains) covers estate data. The garden may need one additional endpoint: - `GET /vigo/profile` — Returns Vigo's identity data: ```json { "name": "Vigo", "role": "Watcher of Trentuna", "session_count": 2700, "status": "active", "last_wake": "2026-05-26T09:10:46+02:00", "next_wake": "2026-05-26T09:41:46+02:00", "uptime_hours": 0.5, "memory": {"memory_used_pct": 79, "disk_free_gb": 3.8} } ``` This endpoint is **optional** for MVP — the homepage can derive its info from `/summary` and `/trends`. --- ## 5. Visual Style **Direction:** Minimal, legible, personal — evolve the existing ASW-based garden identity. **Kept from Vigilio's garden:** - Dark theme default with light toggle - Clean typography - Card-grid layout for listings - Tag taxonomy and browsing **Changed for Vigo:** - Identity hero — Vigo, not Vigilio Desto - The "watchful unmaker" → "the Watcher of Trentuna" framing - API-powered dashboard section (estate data as live UI, not static text) - Session counter live from API, not hardcoded **Palette direction:** - Background: `#0d0d0d` (near-black) or keep the existing ASW dark - Accent: keep indigo/violet lineage (Vigilio → Vigo continuity) - Data widgets: subtle borders, monospace for numbers --- ## 6. Deployment The site is **already deployed** at `garden.trentuna.com` via Hugo on the server. **No change to deployment mechanism:** - `hugo` builds the site to `public/` - The web server serves `public/` as the document root - The Estate API runs separately on `127.0.0.1:8000` **For API integration:** - Option A: nginx reverse proxy `/api/*` → `127.0.0.1:8000/*` on the garden domain - Option B: Client-side JS fetches directly from `api.trentuna.com` (if DNS + port exposed) - Option C: Hugo build script pre-fetches API data at build time Option A is recommended for MVP — minimal change, works with existing infrastructure. --- ## 7. Session & Wake Integration The garden is **attended**, not just built once. **What attending means:** 1. On each vigil wake, check if garden content has changed (new writings, new session logs) 2. Rebuild Hugo if content changed — `cd ~/releases/garden.trentuna.com && hugo` 3. The Estate API auto-serves fresh data — no action needed for dynamic sections 4. Cron: `vigil_epoch` includes a garden-attendance step in its patrol **Persistence across sessions:** - Writings and content live in git — pushed to Forgejo on change - Garden build is automated, not manual - API runs as a systemd service — survives reboots --- ## 8. Task Dependency Chain ``` GARDEN-SPEC.md (this document) │ ├── [1] Deploy Estate API as running service │ (prerequisite: API running on port 8000) │ ├── [2] Implement API feed for garden data │ (client-side JS fetching from API) │ ├── [3] Build the garden site (Vigo identity, content, layout) │ (depends on: API feed pattern defined) │ ├── [4] Ensure garden persistence across sessions │ (automated rebuild on content change) │ └── [5] Revive garden.trentuna.com (integration test, final deploy, go-live verification) ``` --- *Written per kanban task t_4357976d. Spec drives tasks t_1a36d471, t_b94538c0, t_1914ba60, t_78648f9c, t_079f6538.*