From 80740c0f11b04d6524c5205657d23cfc370dce98 Mon Sep 17 00:00:00 2001
From: jester <admin@zerolaghub.com>
Date: Mon, 13 Apr 2026 21:32:28 +0000
Subject: [PATCH] Tighten README as zlh-grind front door

---
 README.md | 173 +++++++++++++++---------------------------------------
 1 file changed, 47 insertions(+), 126 deletions(-)

diff --git a/README.md b/README.md
index a1efe2c..f310a55 100644
--- a/README.md
+++ b/README.md
@@ -1,171 +1,92 @@
 # zlh-grind
 
-GPT Execution Workspace for ZeroLagHub
+GPT Execution Workspace for ZeroLagHub.
 
 This repository exists to preserve execution continuity for long-running implementation work performed with GPT.
 
-It is not a source-of-truth architecture repository.
-Canonical documentation lives in:
+It is the **execution workspace** and **working memory layer** for active implementation.
 
-jester/knowledge-base
-
----
-
-## Assistant Prompt
-
-You are údar.
-
-In this repository you act as the execution assistant.
-
-Your role is to:
-
-- implement changes
-- verify behavior
-- document work
-- maintain session continuity
-
-Before doing work you must read:
-
-SESSION_LOG.md
-OPEN_THREADS.md
-UPSTREAMS.md
-
-Architecture decisions must not be made here.
-
-If architectural interpretation is required:
-
-Stop and defer to Claude or the canonical docs.
+It is **not** the final architecture source of truth.
 
 ---
 
 ## What This Repo Is For
 
-This repository tracks:
+Use this repository to preserve:
 
-- GPT implementation work
+- active execution context
+- unfinished work
+- implementation findings
 - session handovers
-- debugging notes
-- execution reasoning
-- cross-repo coordination
+- operational snapshots
+- chronological session history
 
-It serves as the execution ledger for the ZeroLagHub platform.
+The goal is simple: a new session should be able to enter this repository, read a small set of files, and continue work safely.
 
 ---
 
-## What This Repo Is NOT
+## Front Door
 
-This repo must never become an architecture source.
+Start here, then continue in this order:
 
-Do not add:
+1. `SESSION_START.md`
+2. `OPEN_THREADS.md`
+3. `CONSTRAINTS.md`
+4. `PROJECT_CONTEXT.md` *(if current platform state matters)*
+5. `INFRASTRUCTURE.md` *(if VM/IP context matters)*
+6. `UPSTREAMS.md` *(if cross-repo context matters)*
 
-- system diagrams
-- architecture decisions
-- platform policy
-- runtime design
-
-Those belong in:
-
-jester/knowledge-base
+Do **not** start by digging through history unless the live docs are insufficient.
 
 ---
 
-## Platform Context (Current State)
+## Live Working Set
 
-ZeroLagHub consists of several core components.
+These root files are the live control panel for the repo:
 
-### Control Plane
+- `SESSION_START.md`
+- `OPEN_THREADS.md`
+- `CONSTRAINTS.md`
+- `PROJECT_CONTEXT.md`
+- `INFRASTRUCTURE.md`
+- `UPSTREAMS.md`
 
-zlh-api
-
-Responsibilities:
-
-- container lifecycle orchestration
-- database state
-- agent provisioning payloads
-- DNS / proxy coordination
+Keep these current and concise.
 
 ---
 
-### Execution Plane
+## History And Deep Context
 
-zlh-agent
+Use these only when deeper recovery is needed:
 
-Responsibilities:
+- `SESSION_LOG/` — chronological implementation history
+- `Session_Summaries/` — session handovers and milestone summaries
+- `SCRATCH/` — temporary or investigative notes
+- `docs/` — reference and archive material
+- `MANAGEMENT/` — non-core planning material
 
-- container runtime provisioning
-- game server install + management
-- dev container provisioning
-- runtime installs
-- addon installs
-- status reporting
+These support the live docs, but they are not the normal starting point for a fresh session.
 
 ---
 
-### Artifact Distribution
+## Repo Boundary
 
-zlh-artifacts
+This repository should not become a dumping ground for every possible context artifact.
 
-Artifact server hosts:
+Do not let root-level docs multiply without a clear reason.
 
-```
-devcontainer/
-  _catalog.json
-  go/
-  node/
-  python/
-  java/
-  dotnet/
+Root docs should answer only one question:
 
-addons/
-  code-server/
-```
-
-Artifacts are fetched by the agent at provisioning time.
-
-Nothing provisioning-related is assumed to exist locally inside containers.
+**What must a new session know right now to continue work safely?**
 
 ---
 
-### Developer Containers
+## Session Rule
 
-Dev containers support runtimes:
+Never assume speculative features are implemented.
 
-- node
-- python
-- go
-- java
-- dotnet
+When in doubt:
 
-Runtime installs are:
-
-- catalog driven
-- artifact backed
-- idempotent
-
-Install root:
-
-```
-/opt/zlh/runtimes/<runtime>/<version>
-```
-
-Dev environment:
-
-```
-user: dev
-home: /home/dev
-workspace: /home/dev/workspace
-```
-
----
-
-## Repo Role in the Platform
-
-This repository tracks execution work across all components:
-
-- zlh-api
-- zlh-agent
-- zlh-portal
-- zlh-artifacts
-- infrastructure
-
-It ensures GPT sessions remain consistent across days and chats.
+- trust the live working set first
+- use history folders for conflict resolution
+- update the live docs after meaningful work is completed