title: "Trellis Living Organism — Sovereign Subsumption"

description: "Master architecture and overview of the Trellis local-first AI computing organism."

order: 1

Trellis Living Organism

Trellis is a self-contained, keyboard-centric, local-first computing environment and agentic operating platform running on sovereign local silicon (AMD Ryzen 5 3600 + NVIDIA RTX 3090 Ti 24GB VRAM).

Trellis formally subsumes four prior paradigms into a unified local environment:

┌─────────────────────────────────────────────────────────────────────────────────┐
│                           TRELLIS LIVING ORGANISM                               │
├───────────────────┬───────────────────┬───────────────────┬─────────────────────┤
│     GobboNet      │      Hermes       │     Odysseus      │      Obsidian       │
│ ───────────────── │ ───────────────── │ ───────────────── │ ─────────────────── │
│ • 0-token swarms  │ • Steerable Souls │ • Bounded RAG     │ • Markdown Vault    │
│ • ADR invariants  │ • ChatML <tools>  │ • Subtraction law │ • [[Wikilinks]]     │
│ • Single-file PRs │ • <think> tokens  │ • SQLite Vectors  │ • Daily Note loop   │
│ • Parallel Go/Web │ • agentskills.io  │ • Telemetry ledger│ • Zero Electron     │
└───────────────────┴───────────────────┴───────────────────┴─────────────────────┘

Core Operational Invariants

1. Local Silicon First (0-Token Runtime): Every interactive shell triage, character dialogue, and micro-agent pipeline runs 100% locally on workstation GPU hardware via Ollama (:11434) and llama-server (:11437). Zero daily cloud billing.

2. Surgical Cloud Distillation: Remote cloud models (Gemini API) are restricted strictly to offline, on-demand batch distillation (rag-cloud-indexer) during the nightly Dream Cycle. Zero continuous remote scanning.

3. Go Mastery (CGO_ENABLED=0): All core platform daemons and CLIs are compiled statically in Go with zero runtime dependencies.

4. The Bash Front Door (~/trellis/machine/bin/): The single source of truth for all workstation binaries and agent tools. First in $PATH and mirrored in ~/.local/bin/.

5. Caelestia Desktop Authority: Hyprland + Caelestia Shell (Quickshell QML) governs all desktop presentation, enforcing spatial heuristics between persistent TOP-stack vigil alerts and ephemeral BOTTOM-drawer hearth toasts.

title: "Trellis Agent Platform (TAP) & The Nine Seats"

description: "Dedicated agent platform on port 9090, Pantheon sentinels, Senate deliberators, and the Scribe-Shear Diad."

order: 2

Trellis Agent Platform (TAP) & The Nine Seats

Operating on dedicated port http://127.0.0.1:9090 (machine/bin/tap), TAP unites nine sovereign character seats across two complementary governance bodies:

Governance Model: Pantheon vs. Senate

graph TD
    TAP["Trellis Agent Platform (:9090)"]
    
    subgraph ThePantheon ["The Pantheon (State Sentinels / Arrive Unprompted)"]
        Hestia["Seat 1: Hestia (The Hearthkeeper)<br/>GPU Power / Thermal / VRAM Vigil"]
        Grammateus["Seat 2: Grammateus (The Doorway)<br/>Doc Verification / Visual QA / Evidence"]
        Galatea["Seat 3: Galatea (The Woken)<br/>Emergent Direction / Intent vs Accretion"]
    end

    subgraph TheSenate ["The Senate (Deliberative Council / Convened on Demand)"]
        Atropos["Seat 3: Atropos (The Shear)<br/>Complexity Auditor / Dead Code Pruner"]
        ForgeGoblin["ForgeGoblin (The Mentor)<br/>ADRs / Single-File Invariants"]
        CodeGoblin["CodeGoblin (The Hacker)<br/>Go Materializer / Diff Blocks"]
        AegisGoblin["AegisGoblin (The Shield)<br/>Zero-PII / Loopback Isolation"]
        TheEcho["The Echo (The Mirror)<br/>Operator Heuristics / Mock Testing"]
        Sensei["Sensei (The Compass)<br/>Offline Arch Discovery"]
    end

    TAP --> ThePantheon
    TAP --> TheSenate

The Scribe-Shear Diad (Grammateus • Atropos)

• Grammateus (Seat 2 Chief Scribe): Present from turn 1 of every design phase. Manages specifications with Human-In-The-Loop (HITL) precision, ensuring zero documentation duplication across the tree.
• Atropos (Seat 3 The Shear): The cheerful skeptic. Actively audits the knowledge tree for stale notes and redundant specs, placing pruning stamps and keeping the tree lean.
• The Grammateus Unlazy Axiom: Results are conspicuously absent if Grammateus cannot see them. Every claim of UI fix or feature passage requires an admissible visual receipt.

title: "The Bash Front Door & Key Workstation Binaries"

description: "Single source of truth for workstation binaries in ~/trellis/machine/bin/."

order: 3

The Bash Front Door (~/trellis/machine/bin/)

The single source of truth for all workstation tools lives in ~/trellis/machine/bin/ (first on $PATH and mirrored in ~/.local/bin/).

Key Front Door Binaries

title: "Caelestia Desktop Notification Authority"

description: "Spatial notification heuristics: TOP persistent vigil stack vs. BOTTOM hearth drawer toasts."

order: 4

Caelestia Desktop Notification Authority

Caelestia Shell (Quickshell QML on Hyprland) is the sole notification and toast authority on the workstation. All legacy daemons (mako, dunst) are masked.

Spatial Notification Heuristics

┌─────────────────────────────────────────────────────────────┐
│  TOP-RIGHT DESKTOP STACK (Sky / Persistent Vigil)           │
│  • Persistent until clicked / acknowledged                  │
│  • High-gravity: Asynchronous receipts, thermals, gauntlets │
│  • Command: caelestia-notify send -a "<App>" "<Title>"      │
├─────────────────────────────────────────────────────────────┤
│  BOTTOM-RIGHT IN-SHELL DRAWER (The Hearth / Tactile Chatter)│
│  • Ephemeral (auto-dismisses in 5s)                         │
│  • Allowed to chatter: File edits, test steps, tool dispatches│
│  • Command: caelestia-notify toast <level> "<Title>" "<Msg>"│
└─────────────────────────────────────────────────────────────┘

Material Symbol Ligatures

Bottom toasts require Google Material Symbol ligatures for visual clarity:

palette, brush, checkcircle, info, warning, error, terminal, build, code, doneall, smart_toy.

title: "Go as Lingua Franca & The Materializer"

description: "Communicating in typed Go-pseudocode with // MATERIALISE seams crystallized by CodeGoblin."

order: 5

Go as Lingua Franca & The Materializer

In Trellis, Go is the primary language of thought:

1. Go-Pseudocode Communication

The operator communicates architectural intent in Go-pseudocode — expressive, structured, typed markdown containing // MATERIALISE seams, conceptual interfaces, and sketch blocks:

package sensor

type Reading struct {
    GPU   string  `json:"gpu"`
    Power float64 `json:"power"`
    Temp  int     `json:"temp"`
}

// MATERIALISE: read nvidia-smi power draw and return Reading struct or error
func SampleCard() (*Reading, error) {
    // shell out to nvidia-smi and parse output
}

2. Deterministic Materialization (gobbo materialize)

CodeGoblin parses the Go-pseudocode sketch, resolves all // MATERIALISE seams, applies standard Go idioms (explicit error returns, context propagation, zero-dependency stdlib), and emits strict, compiling production Go.

gobbo materialize "pkg/sensor/card.go" '<Go-pseudocode>'

3. The Expansive Tuning Knob Principle

All seated agents and autonomous swarms must proactively recommend actionable Tuning Knobs & Switches at the conclusion of tasks.

Tuning knobs range from deep internal parameters to high-leverage operator-tool interfaces:

1. Operator Ergonomics & Interface Levers:

• Keyboard chords & CLI twins (Two Doors, One Room).
• Click-to-chat notification triggers (e.g. hestia ready click action).
• Modal flows, interactive REPL defaults, and cognitive friction reducers.

2. Cognitive Flow & Spatial Hierarchy:

• Hearth vs Sky spatial notification routing.
• Tactile progress chatter vs quiet deep focus.
• Dynamic threshold adjustments for the Hearth Sentinel (hestia).

3. Workflow Choreography:

• Multi-agent handoff pipelines (ForgeGoblin 🔨 $\rightarrow$ CodeGoblin 👾 $\rightarrow$ AegisGoblin 🛡️ $\rightarrow$ Grammateus 📜).
• Intent pinning & morning review cadences (northstar).
• Unlazy visual proof & test verification invariants.

4. Interior Silicon & Build Optimization:

• Model routing & zero-token local silicon delegation.
• KV prompt cache reuse & min_p tail-clamping on local GGUF models.
• Go binary stripping (-ldflags="-s -w") and static asset pre-compression (.gz).

title: "Sovereign RAG & Progressive Context Hygiene"

description: "Progressive L0-L3 context tiers, 'Context must pay rent' doctrine, and telemetry ledger."

order: 7

Sovereign RAG & Progressive Context Hygiene

To prevent context bloating and hallucination, Trellis models ingest context through four progressive tiers:

┌─────────────────────────────────────────────────────────────┐
│  Tier 0: Active Shell & PWD Text Files (<500 tokens)        │  -> Instant reflex
├─────────────────────────────────────────────────────────────┤
│  Tier 1: Live Tool Help & AST Manifests (1 - 2 KB)          │  -> Dynamic CLI --help
├─────────────────────────────────────────────────────────────┤
│  Tier 2: Distilled Prior Art Spec Slices (2 - 4 KB)         │  -> Living Canon Slices
├─────────────────────────────────────────────────────────────┤
│  Tier 3: Local SQLite Dense Embeddings (vectors.sqlite)     │  -> Semantic on demand
└─────────────────────────────────────────────────────────────┘

High-Signal Telemetry Ledger (rag-report)

Every interactive turn records throughput and hygiene grade in machine/state/rag_telemetry.jsonl.

title: "Workstation Day-Arc & The Dream Cycle"

description: "Circadian palette shifts, Hestia GPU surveillance, and nightly offline batch distillation."

order: 8

Workstation Day-Arc & The Dream Cycle

Trellis synchronizes workstation aesthetics, GPU thermal protection, and background batch operations to a circadian rhythm:

• Day Work: High-velocity interactive local chat (0 tokens).
• Nightly Dream Cycle (theme dream):
• Palette shifts into midnight obsidian.
• rag-cloud-indexer batch-distills updated markdown files into priorartdigest.json and vectors.sqlite.
• Full automated test gauntlet runs and updates vault/System/Tests.md.

title: "Sovereign Character-Verb Matrix"

description: "Declarative Character Registry, Character.AI compatibility, and favorite tool bindings."

order: 6

Sovereign Character-Verb Matrix

Every entity in Trellis combines a narrative identity with executable workstation verbs.

Universal Character Schema

Stored in agent/personalities/characters/.json with arbitrary portrait CRUD in agent/personalities/portraits/.png.

{
  "name": "ForgeGoblin",
  "slug": "forgegoblin",
  "icon": "build",
  "portrait": "agent/personalities/portraits/forgegoblin.png",
  "desc": "Grill-With-Docs mentor. Formulates 1-paragraph ADRs.",
  "agent": {
    "body": "The Senate",
    "favorite_tools": [
      { "name": "adr_builder", "description": "Formulates 1-paragraph ADRs" }
    ]
  }
}

Access via tap characters and tap character .

Workstation CLI Commands Catalog

All custom utilities located in ~/trellis/machine/bin/.

title: "Upstream Flight Deck & GobboNet Contributions"

description: "Proving ground workflow and clean single-file PR contributions to GobboNet."

order: 9

Upstream Flight Deck & GobboNet Contributions

Trellis acts as an experimental proving ground:

1. Trial Flight: Features run natively on Trellis port :9090.

2. Automated Validation: Gauntlet verifies multi-OS compatibility.

3. Branching: Checkout feature/ in /home/sam/repos/GobboNet.

4. Surgical Porting: Port clean single-file diffs to GobboNet without external dependencies.

title: "Native Markdown Vault & Knowledge Engine"

description: "Obsidian subsumed: Pure Go markdown engine, [[Wikilinks]], and atomic daily note loops."

order: 10

Native Markdown Vault & Knowledge Engine

Trellis replaces Obsidian's heavy Electron layer with a native, pure Go/Python markdown engine:

• Location: ~/trellis/vault/ (Daily/, System/, Characters/, Projects/).
• Wikilinks: Native [[Document Name]] resolution and backlink graph indexing.
• Atomic Daily Loops: Safe atomic upserts (read -> parse -> modify -> write tmp -> rename -> verify) under designated agent headers (## Hearth, ## Doorway, ## Shear).