garden/GARDEN-SPEC.md

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:

  {
    "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.