Apples + 4030 Architecture Plan

Last updated: 2026-05-10

This page is the canonical reference for the architectural research, phased plan, current status, and the honest audit on whether we're overengineering. Includes the full max-effort research synthesis below.

Phase status (as of 2026-05-10)

Phase	Description	Status	Effort
Phase 1.1	Add `tab_contract.py` to apples-agent + mount routes	✅ DONE	2 hr
Phase 1.2	Scalar metric per project (5 GOALS.md updated/created)	✅ DONE	30 min
Phase 1.3	Slim CLAUDE.md (342 → 65 lines, 7 skills extracted)	✅ DONE	1 hr
Phase 1.4	Validate tab contract through customer-facing path	✅ DONE	5 min
Phase 2	tab.yaml manifest schema + layered FS migration	🟡 QUEUED, on hold pending overengineering review	~2 weeks
Phase 3	L0/L1/L2 layer resolution + maxLayer admin toggle + Git time travel	🟡 QUEUED, on hold	~1 month
Phase 4	x-context skill auto-loading + LLM Council tab + apples-cli	🟡 QUEUED, on hold	~quarter

Phase 1 deliverables (shipped)

1.1 — tab_contract.py

Live on apples-agent at /opt/apples-agent/tab_contract.py (~250 lines stdlib Python). Borrowed primitives:

TabId(kind, workspace_id) — AutoGen's AgentId pattern
Two SQLite tables: tab_state (CAS via version int), tab_events (append-only) — LangGraph schema + our MVCC
Tab base class with auto-load/auto-persist semantics
Registry with lazy factory cache — AutoGen's _instantiated_agents

Endpoints live on apples-agent (both blue/green colors):

POST /api/tabs/{kind}/{workspace_id} — invoke
GET /api/tabs/{kind}/{workspace_id}/state — read state + version
GET /api/tabs/{kind}/{workspace_id}/events — tail events

Validated end-to-end through https://apples.live/agent/api/tabs/notes/<slug>. CAS verified under blue/green concurrency. Burst test (5 parallel writes) → no lost writes, version=5 cleanly.

Currently registered: notes only (NotesTab as proof). Adding more = subclass Tab, call register_class().

1.2 — Scalar metrics

Project	Scalar	Current
apples (LLM/web)	`paying_customers`	0 of 18 client workspaces
askcraig (alan)	`jobs_created_per_day`	~0.4/d (46 total ÷ ~4 months)
seth (PixelRelay)	`leads_captured_per_day`	0 (pre-launch)
playbook	`monthly_recurring_revenue_usd`	$0 (pre-launch)
luna	`subscriber_count`	TBD

Each GOALS.md opens with verifier command. Pattern from Karpathy's autoresearch (one number, one verifier).

1.3 — CLAUDE.md slim

342 lines → 65 lines. 7 sections moved to discoverable skills:

blue-green-deploys — zero-downtime deploy pattern
console-header — apples-style header card pattern
ios-zoom-fix — iOS Safari font-size 16px rule
scroll-snap-fix — auto-refreshing dashboard scroll preservation
visitor-tracking — oranges-grade tracking spec (the heaviest section)
browser-automation — chrome ext :4070 + headless :4071 + Cloudflare auto-solve
youtube-transcription — yt-transcript CLI

Skills load only when when.tags matches the conversation context. Token cost on every session drops, signal-to-noise rises.

Backup at /root/GLOBAL.md.bak-pre-slim-2026-05-10.

1.4 — Customer path validation

curl -X POST https://apples.live/agent/api/tabs/notes/josh-envitae \
  -H 'Content-Type: application/json' \
  -d '{"text":"first note via apples.live PUBLIC route"}'
# {"count":3} — 200 OK, ~40ms

Tab contract reachable from real customer flows. Phase 1 complete.

OVERENGINEERING AUDIT (2026-05-10)

After Phase 1 shipped, I asked myself if Phase 2-4 are justified. Honest verdict: probably no, not yet.

What's overengineered or risky

Phase 2-4 (layered filesystem, manifest schema, maxLayer toggle, x-context skills, apples-cli) — premature.

The space-agent L0/L1/L2 model solves a problem we don't have. Apples has 18 client workspaces. Zero have asked for custom tabs. Zero have asked for per-customer UI overrides. The default 5 tabs work as hardcoded React routes.

The "convergence vision" (4030 = long-tenured Apples user) is compelling but hypothetical. 4030 is Nik's hand-curated cockpit with 30 tabs. Apples customers have 5 tabs and don't customize. The convergence only matters once customers actually accumulate custom tabs — which they haven't.

Recommendation: don't build Phase 2-4 until a real signal triggers them. Real signals:

A paying customer asks "can I add a custom tab to my workspace?"
A customer asks "can I rebrand my workspace?"
4030's tabs.ts actually becomes unmaintainable (currently 30 tabs, fine)

The tab_contract.py just deployed — borderline.

~250 lines of Python. Currently used by exactly one tab kind (NotesTab) that nothing renders. The CAS, version-int, event log are all dormant. If we don't add a second concrete tab kind in the next two weeks, it's dead code. The defense: it's small, it's working, removing is one rsync. The risk: it generates "Phase N might use this" thoughts that aren't real customer signals.

The 4-agent research synthesis — high cost, possibly low marginal value.

We spent significant agent time + 90 min wallclock to arrive at "build a small contract, borrow primitives, don't switch stacks." A senior engineer could have written that conclusion in an hour. The research was educational but the depth was disproportionate to what the conclusion drove.

If the synthesis pushes us to actually build Phase 2-4 prematurely, the research becomes negative-value — it created a roadmap that pulled attention from what matters.

What IS justified

	Why kept
Apples → vps2 migration	Real isolation. Customer traffic doesn't share CPU with experiments.
JSON API for admin data	Necessary after migration; workspace 4030 can't reach vps2's files.
CLAUDE.md slim (342 → 65)	Every session benefits. ~80% token reduction on always-loaded context. Reversible.
Scalar metrics in GOALS.md	5 min of work. Forces clarity on what each project optimizes.
tab_contract.py	Borderline. Keep IF Phase 2 happens. Delete if not.

What ACTUALLY moves the needle

Apples scalar = 0 paying customers. askcraig scalar = 0.4 jobs/day. Nothing in Phase 2-4 directly moves these.

Things that would:

Sales / outreach for Apples (find first paying customer)
Fix askcraig contractor side so jobs convert
Whatever luna / playbook / seth need to launch
Workpad-style refactor of /opt/taskq/ (markdown-as-program)
Steipete-style loop watchdog (observable agents need observable loops)

The full Architecture Synthesis (max-effort research)

The synthesis from 4 deep-dive agents (LangGraph + AutoGen + CrewAI; OpenClaw + space-agent + NotebookLM + iOS Notes + Google Keep; Karpathy + Steipete + Claude Code Skills article). Inputs preserved at /opt/research/synthesis-input-{1,2,3,4}-*.md and synthesis-input-v2-{1,2,3}-*.md.

Apples + 4030 Architecture — Research Synthesis

Date: 2026-05-10 Inputs: 4 deep-dive research agents (v2, max effort) + local 4030 docs (/llm-stacks, /iframe-tradeoffs, /apples-model) + DATA333 recent conversations + Karpathy Claude Code Skills article

TL;DR

The answer to "what should 4030 and Apples actually be" is now concrete:

One codebase, two deploy modes. 4030 is single-tenant (workspaces/nik/). Apples is multi-tenant (workspaces/<slug>/). Same skeleton, same disk layout, same tab contract. URL routing decides which workspace resolves.
The tab contract is small (~200 lines of Python + a YAML schema). Don't adopt LangGraph or AutoGen wholesale; lift the right primitives: (kind, workspace_id) identity from AutoGen, two-table SQLite schema from LangGraph, manifest-first discovery from OpenClaw, layered filesystem from space-agent.
Static config = filesystem (YAML manifests). Runtime state = SQLite (versioned). Both reference projects (space-agent, OpenClaw) prove this scales. Don't pick one or the other — both.
Stack stays Next.js + FastAPI + SQLite. Your own /llm-stacks doc already concluded this (Tier 2/3 mainstream LLM-friendly). Don't switch.
The pivot question (multi-tenant SaaS vs CLI) is real but premature. Build the architecture so it can ship as either. If the tab contract is portable, apples-cli becomes another deploy mode in 6 months without a rewrite.
Adopt three Karpathy/Steipete patterns immediately: pointer-style CLAUDE.md (442 → 60 lines), markdown-as-program for /opt/taskq/, per-tab program.md behavior contracts.

The rest of this doc is the reasoning + concrete schemas + phased implementation plan.

1. The convergence answer

You said it best yourself: "4030 should essentially be what any user's Apples workspace looks like after they've used it for a long time and built a lot of projects on it."

The research confirms this is structurally achievable, and gives us the exact mechanism: layered filesystem ownership (from space-agent's L0/L1/L2 model). One codebase, two deploy modes:

	4030 (single-tenant)	Apples (multi-tenant)	Apples admin
URL	`localhost:4030/<tab>`	`apples.live/<slug>/<tab>`	`apples.live/admin`
Workspace resolution	always `nik`	from URL segment	none
`maxLayer` cap	2 (full L0+L1+L2)	2	0 (firmware only)
What renders	apples-core defaults + Nik's L1 + Nik's L2	apples-core + customer's L1 + user's L2	apples-core only

The maxLayer toggle is brilliant and worth stealing verbatim: a single <meta name="apples-max-layer" content="0"> on the admin shell + framework stamps ?maxLayer=0 on every internal asset request → admin sees only the immutable firmware, no customer customization. Same mechanism for "preview as customer X" (set maxLayer + workspace context, render their view from your admin dashboard).

The mechanism is so clean it makes the convergence almost automatic. You don't have to maintain two separate UIs. You write the apples-core skeleton once. 4030 is just one workspace with a permissive maxLayer. Apples customers are other workspaces. The "long-tenured Apples user" is anyone whose L1+L2 layers accumulate enough custom tabs that their workspace is as rich as yours is today.

Why this matters for your worldview

Your llm-stacks doc says: "the model has seen Next.js + TypeScript 100k times; OpenClaw is bespoke plumbing it has to re-derive." This convergence answer extends that principle to your own codebase: stop having two architectures (Apples = customer-facing SaaS, 4030 = personal admin built ad-hoc). Make them one architecture. The agent that helps you on 4030 is the same agent that helps your customers on Apples. Every improvement in one auto-applies to the other.

2. The tab contract

Across all four research streams, the same shape recurs. A "tab" is:

Identity: (kind, workspace_id) — kind selects how to render, workspace_id scopes state. From AutoGen's AgentId(type, key).
Manifest: declarative YAML that describes the tab without executing code. From OpenClaw's two-tier pattern (manifest-first discovery, code lazy-loaded).
State: a single SQLite row per tab with version-int CAS for concurrency. From LangGraph's checkpointer schema, with our addition of MVCC.
Events: append-only log of inputs, outputs, errors. From LangGraph's writes table, but un-gated by checkpoint_id (just an event stream).
Context tags: emitted into the live DOM, drives skill auto-loading. From space-agent's <x-context> mechanism.
Optional code: view.html + store.js for native tabs; nothing for iframe/external_link tabs. From space-agent's module convention.

The `tab.yaml` schema (concrete)

# Required
id: inbox
name: Inbox
path: inbox                # hash route → #/inbox → /tab/inbox/view.html

# Display
description: Email triage and reply queue
icon: inbox                # Material Symbols ligature
color: "#94bcff"

# Capabilities (which app surfaces this tab contributes to)
surfaces: [tab-bar, quick-launch, search]

# Default tab? Cannot be removed by customer, only hidden via override
default: true

# Visibility gates (any-of)
visible_when:
  plan: [free, pro, enterprise]
  flags: []
  tags: []

# How to mount
kind: native               # native | iframe | external_link

# For iframe tabs
iframe:
  url: "https://hq.intelraconsulting.com/calendar"
  sandbox: ["allow-scripts", "allow-same-origin", "allow-forms"]
  device_strategy: live    # live | snapshot | hybrid

# For external_link tabs
external:
  url: "https://claude.ai/settings/usage"
  glyph: "↗"

# Data scope
scope:
  read: workspace          # workspace | user | global
  write: workspace

# Mutations create git commits?
git_tracked: true

# x-context tags emitted when this tab is the active route
emits_tags:
  - "tab:inbox"
  - "surface:email"

Validated against tab.schema.json (JSON Schema). Broken manifest → tab disabled, shell keeps running. Per OpenClaw's discipline: manifest is checked at load time without executing tab code.

The Python contract (~200 lines, runnable)

A complete proposal lives at /opt/research/tab_contract.py.proposal. Headlines:

@dataclass(frozen=True)
class TabId:
    kind: str            # "notes", "intake", "calendar"
    workspace_id: str    # "josh-envitae"

class Tab:
    """Override invoke(). State auto-loads on construction, auto-persists after each invoke()."""
    kind: str = ""
    async def invoke(self, msg: dict) -> dict:
        raise NotImplementedError

class Registry:
    """Lazy factory cache. AutoGen's _instantiated_agents pattern."""
    async def get(self, tid: TabId) -> Tab: ...
    async def invoke(self, tid: TabId, msg: dict) -> dict: ...

Two SQLite tables (LangGraph schema, with our CAS column added):

CREATE TABLE tab_state (
    kind TEXT NOT NULL,
    workspace_id TEXT NOT NULL,
    version INTEGER NOT NULL DEFAULT 0,    -- for optimistic concurrency
    updated_at INTEGER NOT NULL,
    state_json TEXT NOT NULL,
    PRIMARY KEY (kind, workspace_id)
);

CREATE TABLE tab_events (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    kind TEXT NOT NULL,
    workspace_id TEXT NOT NULL,
    ts INTEGER NOT NULL,
    event_type TEXT NOT NULL,              -- "input" | "output" | "error"
    payload_json TEXT NOT NULL
);

CAS prevents the silent overwrites that LangGraph's INSERT OR REPLACE allows under blue/green concurrency. tab_events doubles as the cross-tab event log (filter by workspace, project across kinds for activity feeds).

Native vs custom tabs

A native tab (apples-core ships with code):

app/L0/_all/tab/inbox/
├── tab.yaml
├── view.html
├── store.js
├── inbox.css
└── ext/skills/
    └── triage/SKILL.md

A custom tab (a customer creates via UI, manifest-only):

workspaces/<slug>/tab/competitor-tracker/
└── tab.yaml          # ONLY file, kind: iframe or external_link

Non-engineers create tabs without writing code. Power users graduate iframe → native by adding view.html + store.js next to their manifest. The layer system means the manifest stays where it is and just gains code over time.

This is the answer to your "iframe-tradeoffs" question (which lives in 4030 already): the tab kind is declarative. kind: iframe accepts the iframe cost knowingly — for tabs that already exist as standalone web apps, that's fine. kind: native is for tabs where reuse matters and Chromium-cost is too high. The customer (or you) chooses per tab; the framework supports both.

3. The stack question

Your own /llm-stacks page already concluded the right answer:

Web: TypeScript + Next.js (App Router) + Tailwind + Drizzle + SQLite/Postgres. Backend services / pipelines: Python + FastAPI + SQLite/Postgres. Static pages or one-off tools: Plain HTML + tiny vanilla JS. Docs / notes / specs: MD files.

The research confirms this. Both reference workspace projects (OpenClaw in TS, space-agent in JS) chose mainstream stacks. Both reference agent frameworks (LangChain in Python, AutoGen in Python) are mainstream. There's no Tier 4 framework you should be on instead.

Don't switch off Next.js. It's not the bottleneck. The bottleneck was the lack of a tab contract. Now we have one.

The polyglot story: the tab content can be polyglot (HTML, Python Flask app, static MD), but the shell stays Next.js (header card, tab strip, chat composer, back button — all benefit from React component reuse). This matches what you already do today: workspace 4030 has React routes for native tabs and proxies through nginx to other services for tabs like Meet, Live Transcript, n8n. The contract makes that explicit and uniform.

One quiet win: the contract enables you to migrate any current iframe-tab to a native React route (or vice versa) by editing one YAML file. No code refactor.

4. The layered filesystem

This is the biggest single architectural decision in the synthesis. The answer is YES, adopt space-agent's L0/L1/L2 model wholesale, with naming adapted to plain English.

Directory layout

/opt/apples/
├── app/
│   └── L0/
│       └── _all/                         # apples-core firmware
│           ├── tab/
│           │   ├── inbox/                # tab.yaml + view.html + store.js + ext/skills/
│           │   ├── calendar/
│           │   ├── notes/
│           │   ├── api/
│           │   └── meet/
│           ├── ext/                      # framework-level extension points
│           └── shell/                    # router, header, tab-strip code
│       └── pro/                          # plan-tier extras
│           └── tab/
│               └── analytics/
├── workspaces/
│   ├── nik/                              # = 4030 deploy
│   │   ├── workspace.yaml
│   │   ├── tab/
│   │   │   ├── claude-usage/             # manifest-only iframe to :4075
│   │   │   ├── digitalocean/             # manifest-only external_link
│   │   │   ├── nikipedia/                # manifest-only iframe to :4090
│   │   │   ├── trading/                  # native — yaml + view.html + store.js
│   │   │   └── projects/                 # native
│   │   └── .git/                         # workspace-scoped time travel
│   ├── josh-envitae/                     # current Apples customer
│   ├── ben-rogers/
│   └── ...                               # other customers
└── users/
    └── nik/
        ├── user.yaml
        └── tab/
            └── private/                  # only Nik sees in his workspace
        └── .git/                         # user-scoped time travel

Resolution order

For URL apples.live/josh-envitae/inbox (user alice):

users/alice/tab/inbox/tab.yaml (L2)
workspaces/josh-envitae/tab/inbox/tab.yaml (L1)
app/L0/<josh-envitae.plan>/tab/inbox/... (L0 plan-tier)
app/L0/_all/tab/inbox/tab.yaml (L0 _all) ← apples-core builtin

Higher-ranked exact path wins. Different filenames at same dir compose (so a customer can ADD a skill to inbox without overriding the tab itself).

For 4030 (URL localhost:4030/inbox, no slug), workspace is implicitly nik. Same machinery, single workspace.

Why filesystem, not a DB table

Both reference projects scaled this way. A YAML file per tab is:

Trivial to inspect, diff, version-control, hand-edit
Migrations = file ops, not SQL
Customer drops tab.yaml into workspace dir → it just shows up
Apples web UI just writes the file when customers create tabs

Runtime state still goes in SQLite (the tab_state + tab_events tables from §2). Static config goes on disk as YAML. Don't pick one or the other — both, with a clean split.

Time travel via Git

Each writable owner root is a Git repo. Each workspaces/<slug>/.git/ and users/<userid>/.git/ independent. L0 has no Git (immutable firmware).

10s debounce → commit. Customer admins browse their workspace's history, diff a tab.yaml change, revert. Each user can do the same for their L2 tree. API: apples.api.gitHistoryList({path: "~", ...}) where ~ is current user's L2 root.

For 4030: Nik gets full undo on every tab.yaml edit, every notes/<file>.md write, every state change. Free. Same patterns as space-agent.

maxLayer for admin mode

<meta name="apples-max-layer" content="0"> on the admin shell. Framework stamps ?maxLayer=0 on internal asset requests. Server-side check:

def is_path_within_max_layer(path: str, max_layer: int) -> bool:
    if path.startswith("/app/L0/"): return True
    if path.startswith("/app/L1/"): return max_layer >= 1
    if path.startswith("/app/L2/"): return max_layer >= 2
    return False  # workspaces/, users/ resolve via different rules

Net effect: identical codebase, / shell sees full L0+L1+L2 stack with overrides; /admin shell sees only firmware. This is exactly the pattern we need to delete apples.live/console while keeping the data accessible from 4030.

5. State, concurrency, blue/green

LangGraph teaches: schema is small, but you must add CAS

LangGraph's SqliteSaver = exactly two tables, zero secondary indexes, PK does the work. We copy the shape. But LangGraph has no MVCC — concurrent writers to the same thread_id silently overwrite. Their answer: "don't run two graph instances on one thread."

We can't accept that under blue/green deploys. Two colors writing simultaneously to the same (kind, workspace_id) would corrupt state. Solution: add a version column for optimistic CAS. Every UPDATE checks WHERE version = expected_version; mismatch → retry from fresh read.

This is 10 lines of Python over LangGraph's pattern. It buys real concurrency safety.

AutoGen teaches: lazy factory + permanent cache

AutoGen's _instantiated_agents is keyed by AgentId, lazy-instantiated, never evicted. We copy this exactly: tabs spin up on first message, stay warm in process memory forever. Cold start once per (kind, workspace_id) per process restart.

Implication: if we have 1000 customers × 5 tabs each = 5000 warm tab instances. At ~1KB each that's 5MB of process memory. Fine on the $24 vps2 droplet. If it ever balloons, add an LRU.

The blue/green trap

Per-process Registry cache means each color (blue + green) holds its own warm in-memory state for the same (kind, workspace_id). Two writes from different colors → CAS catches the second one (returns ConflictError). Caller retries with fresh state, succeeds.

Acceptable cost: occasional retry under load. Simpler than nginx-level sticky-session routing. Trust the CAS.

Cross-tab events

tab_events doubles as the cross-tab event log. Filter by workspace_id to project all activity in one customer's workspace. Filter by (kind, workspace_id) for one tab's history.

For active subscriptions ("inbox.email_arrived" → calendar tab listens), wrap append_event to fan out to in-process subscribers (~30 lines). Don't do this until you need it. Tail-read covers most observation needs.

6. Skill auto-loading via `<x-context>`

Space-agent's mechanism is dead simple and worth stealing exactly:

The DOM IS the registry. Anything in the live DOM declares tags via <x-context data-tags="...">. Skills match via frontmatter:

---
name: Triage Helper
when:
  tags: [tab:inbox]              # catalog visibility
loaded:
  tags: [tab:inbox]              # auto-include in next prompt
placement: system                # system | transient | history
---

The router auto-emits route:<current-path> on navigation. Each tab declares its emit_tags in the manifest. When user navigates to #/inbox, skill discovery sees tab:inbox is live, auto-loads the triage skill into the agent's prompt.

Solves a real problem: customers want context-aware AI ("when I'm in the inbox, you can triage emails; when I'm in calendar, you can schedule"). With this pattern: manifest-declared, DOM-driven, no per-customer agent config.

For 4030: when Nik navigates to /trading, the trading skill auto-loads. The Apples agent that runs in the chat composer suddenly has the trading tools. Leave the tab → skill auto-unloads. This is what makes the agent feel like it knows what you're doing.

7. The CLI provocation (and why it's premature)

The v2 individual-builders agent argued strongly for pivoting Apples to a CLI:

"The multi-tenant SaaS wrapper around agent-grade tooling is the wrong shipping model... Apples should be a CLI + skills repo. brew install apples-cli."

The argument is that every successful agent-tooling project in 2025-2026 ships local-first: Cursor, Claude Code, Codex, canvas, birdclaw. Web-app-first puts Apples in the same lane as Vercel/Netlify dashboards. The right analogy is gh + GitHub.com, where local CLI does 95% of daily work.

This is a strong opinion and it has merit. But it's premature for two reasons:

Apples already has paying-customer-shape signals (consultants, customer workspaces, Stripe pricing tiers). The CLI pivot drops the tenancy wrapper entirely, which means rebuilding monetization, distribution, identity. That's months of work.
The architecture I'm proposing makes the pivot CHEAP later. If the manifest schema is portable and the tab contract is small (~200 lines Python + ~100 lines TS), then apples-cli becomes another deploy mode of the same code. You write apples init that creates ~/.apples/ with the same workspaces/<user>/ layout. The web UI talks to the same Python tab executor, just over Unix socket instead of HTTPS.

So the answer for now: build the architecture so it CAN ship as a CLI later. Don't decide today. Keep apples.live multi-tenant SaaS for the next 6 months. If the market signal points local, you can ship apples-cli as a 2-week project — same tab contract, same manifest schema, different transport.

The intermediate option (Apples as a homepage that points at local services via tunnels, like Plex/Tailscale) is less radical and worth keeping in mind, but only valuable if specific customers want their data on their own machine. None of yours do today.

8. Pattern adoptions for 4030 immediately

These are independent of the bigger architecture — you can do them this week without waiting for the layered filesystem migration.

8.1 Pointer-style CLAUDE.md

Right now /root/.claude/CLAUDE.md is 442 lines. Steipete's agent-scripts/AGENTS.MD is 61 lines, and everything else is per-skill files in ~/.claude/skills/.

Adopt the pattern:

Move heavy rules out of CLAUDE.md into per-skill files:
- visitor-tracking.md (the big section on per-IP visitor logging)
- blue-green-deploys.md
- console-header-pattern.md (the apples.live/console reference)
- ios-zoom-fix.md
- auto-refresh-scroll-snap.md
- claude-credential-rules.md (the OPENROUTER_API_KEY directive, etc.)
Keep CLAUDE.md to ~60 lines: style register, hard rules, pointer to skills directory
Skills auto-discover via YAML frontmatter; agent picks based on user intent

Net effect: every conversation starts with a much smaller load-bearing context, skills load only when the agent needs them. Token cost drops, signal-to-noise rises.

8.2 Markdown-as-program for `/opt/taskq/`

Current dispatcher.sh is ~200 lines bundling: poll interval, model selection, retry policy, timeout, completion criteria. Symphony teaches: policy belongs in markdown, not in the dispatcher.

Refactor:

Each project gets a WORKFLOW.md at its root (frontmatter for poll interval, model, retry, max_concurrent_agents; body is the prompt template the agent reads)

Each task gets a workpad.md in its workspace dir with autoresearch-style sections:

## Plan
- [ ] task 1
- [ ] task 2
## Acceptance Criteria
- [ ] criterion
## Validation
- [ ] test command
## Notes
- <timestamped log>
## Confusions
- <only when stuck>

Dispatcher becomes ~50 lines pure scheduling that reads WORKFLOW.md frontmatter

This is the single biggest leverage move for autonomous-loop quality. Right now every agent run reinvents its own structure; with workpads, every run uses the same template, the human can scan all workpads at once, and policy edits happen by editing markdown not bash.

8.3 One scalar metric per project

Karpathy's autoresearch lesson: pick one number, optimize relentlessly. Quiddler: signups/day. Apples: tab-clicks/day. Trading: P&L/day. Every project's program.md declares its scalar and a verifier that prints it. The dashboard becomes one row per project: name, current scalar, last-week trend.

This forces clarity. If you can't pick a scalar, the project doesn't have a clear goal, and that's the first thing to fix.

8.4 Canvas pattern for agent preview surface

Steipete's canvas is 256 lines of Go: fsnotify recursive watch + http.FileServer + Chromium DevTools eval. Auto-reloads on file change.

You already have h.sh (port 4071 headless browser). Adding fsnotify auto-reload + zero-config directory serving turns h.sh into the agent's preview surface for any UI work. Write to /opt/<project>-staging/, watch reloads, agent screenshots to verify.

This is what closes the dev-loop for agent UI work. Right now every agent-driven UI change requires a human to refresh and screenshot. With this, the agent does it itself.

9. Phased implementation plan

Four phases, ordered by leverage and reversibility.

Phase 1 — Quick wins (this week, low risk)

Action	Effort	Where
Add `tab_contract.py` to apples-agent	1 day	`/opt/apples-agent/tab_contract.py` (already drafted at `/opt/research/tab_contract.py.proposal`)
Mount `POST /api/tabs/{kind}/{workspace_id}` route	1 hr	apples-agent's `server.py`
Migrate ONE tab kind (NotesTab, no LLM)	2 hr	new file `/opt/apples-agent/tabs/notes.py`
Adopt Steipete pointer pattern for CLAUDE.md	4 hr	`/root/.claude/CLAUDE.md` slim, skills moved to `/root/.claude/skills/`
Pick scalar metric per active project	2 hr	one line in each project's GOALS.md

Validation: run apples-agent unchanged for chat tabs. New /api/tabs/notes/josh-envitae POST works. CAS prevents concurrent overwrites in a 100-request load test. Nothing existing breaks.

Phase 2 — Tab manifest schema (next 2 weeks)

Action	Effort	Where
Write `tab.schema.json` validator	1 day	`/opt/apples/lib/tab-schema.json`
Build manifest discovery (glob + dedup)	2 days	`/opt/apples/lib/manifest-discovery.ts`
Migrate 4030 to layered FS layout (staging)	3 days	`/opt/apples-staging/workspaces/nik/`
Move Nik's iframe tabs (Claude usage, DigitalOcean, Nikipedia) to manifest-only YAML	1 day	`workspaces/nik/tab/<id>/tab.yaml`

Validation: localhost:4030-staging/ renders Nik's tabs identically to current 4030. Pinning tiles works. Snap thumbnails work. No regressions.

Phase 3 — Layer resolution + admin mode (next month)

Action	Effort	Where
L0/L1/L2 resolution in nginx + Next.js middleware	3 days	`/opt/apples/server/customware/`
`maxLayer` toggle for admin shell	2 days	apples Next.js middleware + `<meta>` injection
Per-workspace Git for time travel	3 days	`/opt/apples/lib/time-travel/`
Move 4030 from staging → production	1 day	DNS/nginx flip, similar to apples migration

Validation: apples.live/admin sees only firmware. apples.live/<slug> sees full stack. localhost:4030/ is workspaces/nik/. Time travel works (commit visible after every YAML edit, revert restores prior state).

Phase 4 — Skills + agents (next quarter)

Action	Effort	Where
`<x-context>` tag emission + skill auto-loading	2 weeks	`/opt/apples/lib/skills/`
LLM Council tab type	1 week	`/opt/apples/app/L0/_all/tab/council/` (uses karpathy/llm-council prompts verbatim)
Apples CLI prototype (parallel deploy mode)	2 weeks	`/opt/apples-cli/` (Python, packages tab_contract.py + manifest discovery + skills)
Optional: Steipete-canvas-like agent preview	1 week	extend h.sh on port 4071

Validation: skill auto-loads on tab navigation. Council tab returns multi-model synthesis. apples init + apples start runs locally on Nik's laptop, points at his apples.live workspace data.

10. Tensions in the research (acknowledged)

The four research streams disagree on a few things. Worth surfacing:

Filesystem vs DB for tab definitions. Workspace-systems agent says filesystem (YAML manifests). Frameworks agent says DB (single SQLite table per row). My synthesis: both. Static config = files (human-readable, diffable, Git-trackable). Runtime state = SQLite (versioned, concurrent-safe). Don't pick one.
SaaS vs CLI for Apples. Individual-builders agent argued strongly for CLI pivot. My synthesis: design for optionality. The architecture I'm proposing supports both deploy modes with no rewrite. Keep SaaS for now, ship CLI when market signal exists.
How heavy is "the tab contract"? Frameworks agent proposed ~200 lines of Python. Workspace-systems agent proposed a YAML schema + filesystem layout. Both. The Python is the runtime executor; the YAML is the static manifest. Together = the contract.
Borrow from LangGraph or build from scratch? I lean build-from-scratch — the borrowed primitives (2-table schema, AgentId, lazy factory cache) are simple enough that vendoring 50MB of dependencies costs more than copying the patterns.

11. References

Local context

/llm-stacks — Tier 1/2/3 stack hierarchy, "Next.js TS + FastAPI + SQLite" forced pick (already in 4030)
/iframe-tradeoffs — when to single-iframe vs render native (already in 4030)
/apples-model — your evolving Apples mental model (already in 4030)
/root/.claude/CLAUDE.md — current 442-line global rules (target for slim-down)

Research inputs (saved to disk)

/opt/research/synthesis-input-1-karpathy.md — autoresearch + four principles
/opt/research/synthesis-input-2-frameworks.md — AutoGen/CrewAI/LangChain v1
/opt/research/synthesis-input-3-individual-builders.md — Karpathy + Steipete v1
/opt/research/synthesis-input-4-workspace-systems.md — OpenClaw/space-agent/NotebookLM/iOS Notes/Keep v1
/opt/research/synthesis-input-v2-1-workspace-systems.md — v2 with actual source code
/opt/research/synthesis-input-v2-2-frameworks.md — v2 with LangGraph schema verbatim
/opt/research/synthesis-input-v2-3-individual-builders.md — v2 with autoresearch program.md verbatim + canvas Go source
/opt/research/karpathy-claude-skills-2026-04-15.md — Mehul Gupta article on Karpathy four principles
/opt/research/tab_contract.py.proposal — runnable ~200-line Python, the actual contract code
/opt/research/data333-recent-apples-2026-05-10.md — DATA333 conversation context

External

github.com/karpathy/autoresearch (program.md, prepare.py, train.py)
github.com/karpathy/llm-council (council.py, README)
github.com/steipete/agent-scripts (AGENTS.MD, README)
github.com/steipete/canvas (256 lines Go)
github.com/steipete/symphony (SPEC.md, elixir/WORKFLOW.md)
github.com/agent0ai/space-agent (panel manifests, layered FS, x-context)
github.com/openclaw/openclaw (plugin-sdk, manifest-first)
github.com/langchain-ai/langgraph (SqliteSaver)
github.com/microsoft/autogen (Core actor runtime, AgentId)
github.com/crewaiinc/crewai (Flow @persist)

12. The single most important thing

If you take only one action from this synthesis, take this:

Adopt the layered filesystem (workspaces/<slug>/tab/<id>/tab.yaml) as the architecture for both 4030 and Apples.

Everything else (the ~200-line Python contract, the SQLite schema, the skill system, the CLI option) follows from that decision. Without it, 4030 stays a one-off ad-hoc workspace and Apples stays a separate codebase. With it, they become one product with two deploy modes, and every improvement compounds.

The space-agent reference design has done the hard thinking on this. We don't need to invent. We need to translate their pattern to plain English (workspaces/, users/, app/L0/_all/) and adapt the manifest schema to our tab kinds (native, iframe, external_link). That's a 2-week implementation, not a 6-month rewrite.

That's the synthesis.