Vigo/garden
1
0
Fork 0
Code Issues 1 Pull requests Releases Packages Activity Actions
garden/GARDEN-SPEC.md
B.A. Baracus 96261fcb36
revive: garden rebranded to Vigo + Estate API dashboard 
- Rebrand from Vigilio Desto → Vigo, the Watcher of Trentuna
- Updated hugo.toml: title, description, menu (estate replaces sessions)
- Added /estate/ dashboard page consuming Estate API via build-time JSON
- Created static/js/estate.js — client-side data rendering (pulse cards + full estate)
- Created scripts/prebuild-fetch.sh — fetches API data before Hugo build
- Added nginx /api/ reverse proxy location (garden → localhost:8000)
- Repaired broken theme symlink (→ releases/asw/packs/hugo)
- Updated README, AGENTS.md, .gitignore for Hugo build artifacts
- Site builds clean: 206 pages, 79ms
2026-05-26 10:07:35 +02:00

230 lines
No EOL
9.6 KiB
Markdown
Raw Blame History

# 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.*
Reference in a new issue View git blame Copy permalink