THE WORKSPACE HANDBOOK

Manual & data dictionary.

How to use the lab. What the data means. Where it lives.

Source reviewed September 26, 2026 · v1 · Implementation reference, not a live service audit

Learn locally

Lessons and triggers simulate workflows. They do not operate your business systems.

Inspect evidence

Repository reports sample source. Every finding needs its scope and revision.

Connect deliberately

Live coaching, voice and Jev require configured providers. Memory continuity is manual.

Owner manual

Follow a workflow below. Expand only the instructions you need.

01Start here

Use Large text in the top bar to switch to Larger text. Your selection and light/dark theme are saved in this browser. Browser zoom also remains available.
Choose a project and use case. Project cards are teaching examples; they are not live connections to those businesses.
Open Framework → Understand. Select each responsibility to see what it owns.
Run a Harness lesson. At Permission, allow or deny the sample operation. Inspect the outcome and Evidence before calling it successful.

02Inspect your repository

Open Framework → Inspect repo. Enter the public repository root: https://github.com/owner/repository. Branch, file, query and fragment URLs are rejected.
The server pins one commit and samples up to 12 eligible files. Expand each finding to see the source path, line and next verification. A matching word is a signal, not a verified integration.
For private code, select up to 12 local text files totaling at most 100,000 bytes. Inspection happens in your browser. The resulting report can contain code excerpts and enters coach context; review it before asking the connected coach.
The Agent Lab baseline is a saved snapshot, not a live rescan. Reinspect after source changes. Neither method runs the repository or performs a complete security audit.

03Try Jev safely

Open Framework → Try Jev. Calculation, Relevance, Architecture and Missing evidence are illustrative examples with no model call.
Live shadow mode sends your task to TypeSafe and recommends code, jev, reasoning or review. It requires a server-side TypeSafe key and service storage.
No recommendation executes a tool. Confidence below 0.85, or a review choice, suggests review. The threshold is illustrative and has not been validated for production.

04Give the coach context

Open Framework → Context. Write your goal and owner notes, then review the generated brief. Notes are user-provided, not verified facts.
The in-app coach receives the brief with selected workspace context when connected. Copy coaching context and paste it into a new ChatGPT conversation for continuity.
There is no automatic ChatGPT retrieval or cross-device memory connection. Browser data is not a shared project knowledge base.

05Practice the complete workflow

Harness: select a stage, run or pause the lesson, inspect a handoff, or compare what breaks without that step. Approval belongs to the learner.
Build: inspect proposed pseudocode and practice ordering the seven handoffs. The snippets are not automatically installed in your repositories.
Triggers: test event, time, state, threshold, human, intelligence and dependency conditions. These run locally; they do not schedule production jobs.
Stack explains provider roles. Evidence lists scripted lesson events; Export downloads the current project/use-case evidence as JSON. A verified lesson is not a verified production outcome.

06Chat and voice

Public visitors receive a signed, eight-hour learning-session cookie; ChatGPT sign-in is not required for the public lesson. Cookies must be enabled.
Without an OpenAI connection, the coach uses scripted lesson guidance. Open-ended coaching and voice require OpenAI and service storage.
Start voice requests microphone access and connects through OpenAI WebRTC. Use mute, End voice and Follow me to control the conversation and workspace updates.
A configured key does not prove provider access. If a connection fails, inspect the visible error; do not assume the voice or model ran.

07Troubleshooting and ownership

Repository unavailable: confirm it is public and use its root URL; try local source files when GitHub is rate-limited.
Connection missing: configure OPENAI_API_KEY or TYPESAFE_API_KEY as server secrets and the DB binding. Public lessons also use PUBLIC_LAB_ENABLED and VISITOR_SESSION_SECRET. TYPESAFE_MODEL is optional. Never paste keys into notes or source samples.
Session error: reload to renew the learning session, or open the app in a new browser tab. Microphone blocked: allow it in browser site settings; an embedded preview may require opening the published app in its own tab. Rate limit: wait for the applicable minute or daily window. Clipboard unavailable: select the brief and copy manually.
Browser storage unavailable: copy your brief and export lesson evidence before leaving. Clearing site data removes local progress and notes, but does not delete server usage records.
The owner should refresh this reference when contracts change. Server retention/deletion automation and durable project memory are not implemented by the documented schema.

Data dictionary

Field names match the implementation. Optional fields may be absent; nullable fields may explicitly contain null.

Storage boundary

Browser records stay on this device and browser profile. D1 stores counters and voice receipts. It does not currently store repository reports, project briefs or the lesson catalog as shared project memory.

Project & use case10 entries

Versioned source code; teaching catalog

Source: lib/studio.ts

Field	Type / rule	Meaning
`Project.id / UseCase.id`	string	Stable catalog identifier; a use case belongs to a project.
`name / short / mark`	string	Display name, compact name and visual initials (short and mark are project fields).
`agent / category / purpose`	string	Named assistant, business category and intended purpose.
`repo / website`	optional URL string	Reference links; their presence does not establish a live connection.
`evidence`	string	What was reviewed and what remains unverified.
`stack / useCases`	string[] / UseCase[]	Described technologies and the project’s lesson scenarios.
`request / context / decision`	string	Sample request, required information and proposed model reasoning.
`permission / operation`	string	Authorization boundary and named sample tool.
`sample / verification / outcome`	string	Fictional result, how to check it and intended business result.
`events`	string[]	Example event for each of the seven trigger families.

Workspace context17 entries

localStorage: agent-lab-studio-v1 → context; sent to connected coach

Source: lib/lab.ts · app/page.tsx

Field	Type / rule	Meaning
`view / scenario`	enum	Foundations view: walk, build, triggers. Scenario: lead, quote, renewal.
`index / triggerStep`	integer 0–6	Selected workflow stage and foundations trigger position.
`approved`	boolean \| null	Learner approval; null means no decision yet.
`discount`	number 0–30	Percentage discount for the fictional margin example.
`selectedTrigger`	string \| null	Selected trigger family; maximum 30 characters.
`tiles`	7 unique stage IDs	Ordering exercise: ask, pack, model, gate, tool, return, finish.
`frameworkContext`	optional string ≤10,000	Generated coaching brief attached to workspace context.
`studio.sessionId`	string ≤80	Local learning session identifier; not a voice-session record.
`studio.projectId / useCaseId`	string ≤60	Selected catalog project and lesson.
`studio.activeTab`	enum	framework, projects, harness, build, triggers, stack, evidence. Reference is a separate route.
`studio.revision`	nonnegative integer	Local context change counter, not a Git revision.
`studio.selectedTool / failureStep`	string \| null / integer \| null	Inspected tool and removed-step comparison (0–6).
`studio.simulation`	enum	idle, running, paused, waiting, verified, failed, denied, canceled.
`studio.recentActions / learned`	string[]	Up to 12 recent labels and 100 comprehension markers.
`studio.follow`	boolean	Follow workspace navigation during voice.
`studio.triggerStatus`	optional enum	idle, waiting, verified, failed, denied, canceled.
`theme / reading / events`	string / string / EvidenceEvent[]	Sibling values alongside context in the saved browser record.

Lesson execution & receipts11 entries

Browser workspace context and local evidence ledger

Source: lib/lab.ts · lib/execution.ts · lib/studio.ts

Field	Type / rule	Meaning
`execution.id / cursor / completed`	string / integer / integer[]	Run ID, active position (0–6), completed positions (up to 7).
`execution.receipt`	optional object	Returned sample operation and verification record.
`receipt.projectId / useCaseId / operation`	string	Identifies which lesson and tool produced the result.
`receipt.result`	string \| object	Sample text or deterministic margin calculation.
`result.revenue / cost / profit`	number	Fictional money inputs and result, in the example’s currency.
`result.margin / discount`	number	Percentage values, not fractions.
`receipt.checked`	boolean	Local lesson result was checked; no production certification.
`EvidenceEvent.id / runId`	string	Event identifier and associated lesson run.
`time`	ISO date-time string	Browser-recorded event time.
`stage / status / detail`	string	Handoff, outcome label and explanatory evidence.
`projectId / useCaseId / source`	string	Lesson identifiers; source is always Scripted lesson. The browser keeps up to 80 events.

Trigger inputs5 entries

studio.triggerInputs in browser state

Source: lib/lab.ts · lib/studio.ts

Field	Type / rule	Meaning
`clock`	number 0–100,000	Simulated hours; time condition is due at 24.
`threshold`	number 0–100	Sample score; condition is met at 80.
`eligible / signal / duplicate`	boolean	Business eligibility, lesson signal and duplicate replay condition.
`approved`	boolean \| null	Trigger-specific learner approval.
`dependency`	enum	pending, complete or failed upstream task.

Repository report & findings10 entries

localStorage: agent-lab-framework:<projectId> → report; no report table

Source: lib/framework.ts · app/api/repo-inspect/route.ts

Field	Type / rule	Meaning
`repo`	string	Repository URL, local sample label, or saved baseline identity.
`revision`	string	Git commit SHA for public inspection; local samples are explicitly unverified.
`inspectedAt`	ISO date-time string	When this report was generated, not the repository’s last modification date.
`files / totalFiles`	string[] / number	Sampled paths and listed file count. Truncated GitHub trees make totalFiles a lower bound.
`partial`	boolean	Signals limited coverage; current inspections are partial.
`findings`	Finding[]	Static signals for Interface, Agent, Jev, Triggers, Memory and Harness controls.
`Finding.layer / status`	string / enum	Layer name; Observed or Needs review. Observed means a pattern matched.
`Finding.evidence / next`	string	Path, line and short excerpt; recommended next verification.
`limits`	string[]	Coverage warnings and explicit audit limitations.
`SourceFile.path / content`	string	Temporary raw input for inspection; raw file arrays are not saved in browser storage by this workflow.

Coaching brief & messages6 entries

Brief inputs in browser; messages in component memory

Source: app/framework-lab.tsx · lib/framework.ts · app/use-coach.ts

Field	Type / rule	Meaning
`repo / goal / notes`	string	Saved framework inputs. Goal ≤500 characters; notes ≤1,500; repo ≤200.
`report`	RepoReport \| null	Saved static inventory used to build the brief.
`Message.id / role / content`	string / enum / string	Local conversation message; role is user or assistant.
`voice / scripted / streaming / stopped`	optional boolean	Message origin and presentation state.
`tool`	optional string	Displayed operation receipt.
`portable brief`	Markdown string	Goal, review date, source revision, findings, notes and next-session instructions. Copying shares it only where you paste it.

Jev shadow decision9 entries

Current UI state; decision is not saved to a database

Source: app/api/jev/route.ts · app/framework-lab.tsx

Field	Type / rule	Meaning
`state`	string 10–10,000	Request task sent to TypeSafe.
`model`	string	Provider-returned model identity. Default request model is jev-latest unless configured.
`answers.route.type / choice`	choice / enum	Recommended route: code, jev, reasoning or review.
`confidence`	number 0–1	Provider confidence; not proof of correctness.
`probabilities`	record of 4 numbers	One 0–1 value per route; sum must be within 0.02 of 1.
`latencyMs`	number	Elapsed server time around the provider request.
`mode / executed`	shadow / false	No recommended operation is executed.
`policy / thresholdNote`	string	Review suggestion and explanation of the illustrative 0.85 threshold.
`usage`	optional unknown	Provider payload; no normalized cost calculation is implemented.

Server table: ai_limits2 entries

Cloudflare D1; operational counters, not project memory. Guest limits also apply per network and across the public site.

Source: db/schema.ts · lib/server.ts · lib/framework-server.ts

Field	Type / rule	Meaning
`id`	TEXT primary key	Composite user + request kind + minute bucket; daily IDs include day and a UTC epoch-day bucket.
`count`	INTEGER NOT NULL	Incremented request count, including attempts that may later fail. Chat: 15/minute, 200/day. Voice: 3/minute, 20/day. Repo and Jev: each 6/minute, 100/day. Guests additionally have daily network/site limits: chat 40/200, voice 6/20, repo and Jev each 20/100.

Server table: voice_sessions6 entries

Cloudflare D1; server usage receipts

Source: db/schema.ts · app/api/live-session/route.ts · app/api/live-usage/route.ts

Field	Type / rule	Meaning
`id`	TEXT primary key	Voice session identifier.
`user_id`	TEXT NOT NULL	Authenticated workspace user; usage updates require the same user.
`created_at`	INTEGER NOT NULL	Creation timestamp in Unix milliseconds.
`closed_at`	nullable INTEGER	Last close-report timestamp in Unix milliseconds.
`usage`	nullable TEXT	Serialized JSON receipt; client close reports are labeled client_session_closed and are not billing proof.
`finalized`	INTEGER NOT NULL, default 0	0 = open/unfinalized; 1 = final. Finalized rows are not updated by the usage endpoint.

API contracts

POST endpoints require the same origin, a valid platform identity or signed public lesson session, and service storage. AI and voice also require OpenAI; live Jev requires TypeSafe. Errors return an error message with an HTTP status.

`GET /api/ai-status`

No body

Sets the signed guest session cookie when public lessons are enabled. Returns sessionReady, accessMode, configuration flags, model labels, missing connections; providerAccess remains unverified.

`POST /api/repo-inspect`

{ repo }

Pinned static RepoReport; public GitHub only. Up to 12 files, 10,000 characters per file and 60,000 characters total.

`POST /api/jev`

{ state }

Validated shadow recommendation; 12-second provider timeout; no execution.

`POST /api/assistant`

{ context, messages, stream? }

Coach response and bounded lesson tools; up to 24 messages of 4,000 characters each.

`POST /api/live-session`

{ sdp, context }

OpenAI WebRTC session negotiation; SDP starts with v=0 and is at most 64,000 characters.

`POST /api/live-usage`

{ sessionId, finalized, usage? }

{ saved } records whether an owned, unfinalized voice row changed.

Common errors: 400 invalid input · 401 session missing · 403 origin rejected · 413 input too large · 429 limit reached · 502 provider failure · 503 connection missing. Public inspection may return 422 when no readable source is found.

Key terms

Agent: The model-driven worker that reasons and explains.
Harness: Application code surrounding the model: context, tools, permissions, limits and checks.
Jev: Optional model for a bounded judgment; code interprets its answer.
Trigger: The condition or event that starts work.
Memory: Stored information; context is the selected information supplied for a turn.
Tool: An allowed operation with validated inputs and a result.
Shadow mode: Observe a recommendation without executing it.
Evidence: A source or result supporting a claim; its scope and date matter.

Field

Type / rule

Meaning

Project.id / UseCase.id

string

Stable catalog identifier; a use case belongs to a project.

name / short / mark

string

Display name, compact name and visual initials (short and mark are project fields).

agent / category / purpose

string

Named assistant, business category and intended purpose.

repo / website

optional URL string

Reference links; their presence does not establish a live connection.

evidence

string

What was reviewed and what remains unverified.

stack / useCases

string[] / UseCase[]

Described technologies and the project’s lesson scenarios.

request / context / decision

string

Sample request, required information and proposed model reasoning.

permission / operation

string

Authorization boundary and named sample tool.

sample / verification / outcome

string

Fictional result, how to check it and intended business result.

events

string[]

Example event for each of the seven trigger families.

Field

Type / rule

Meaning

view / scenario

enum

Foundations view: walk, build, triggers. Scenario: lead, quote, renewal.

index / triggerStep

integer 0–6

Selected workflow stage and foundations trigger position.

approved

boolean | null

Learner approval; null means no decision yet.

discount

number 0–30

Percentage discount for the fictional margin example.

selectedTrigger

string | null

Selected trigger family; maximum 30 characters.

tiles

7 unique stage IDs

Ordering exercise: ask, pack, model, gate, tool, return, finish.

frameworkContext

optional string ≤10,000

Generated coaching brief attached to workspace context.

studio.sessionId

string ≤80

Local learning session identifier; not a voice-session record.

studio.projectId / useCaseId

string ≤60

Selected catalog project and lesson.

studio.activeTab

enum

framework, projects, harness, build, triggers, stack, evidence. Reference is a separate route.

studio.revision

nonnegative integer

Local context change counter, not a Git revision.

studio.selectedTool / failureStep

string | null / integer | null

Inspected tool and removed-step comparison (0–6).

studio.simulation

enum

idle, running, paused, waiting, verified, failed, denied, canceled.

studio.recentActions / learned

string[]

Up to 12 recent labels and 100 comprehension markers.

studio.follow

boolean

Follow workspace navigation during voice.

studio.triggerStatus

optional enum

idle, waiting, verified, failed, denied, canceled.

theme / reading / events

string / string / EvidenceEvent[]

Sibling values alongside context in the saved browser record.

Field

Type / rule

Meaning

execution.id / cursor / completed

string / integer / integer[]

Run ID, active position (0–6), completed positions (up to 7).

execution.receipt

optional object

Returned sample operation and verification record.

receipt.projectId / useCaseId / operation

string

Identifies which lesson and tool produced the result.

receipt.result

string | object

Sample text or deterministic margin calculation.

result.revenue / cost / profit

number

Fictional money inputs and result, in the example’s currency.

result.margin / discount

number

Percentage values, not fractions.

receipt.checked

boolean

Local lesson result was checked; no production certification.

EvidenceEvent.id / runId

string

Event identifier and associated lesson run.

time

ISO date-time string

Browser-recorded event time.

stage / status / detail

string

Handoff, outcome label and explanatory evidence.

projectId / useCaseId / source

string

Lesson identifiers; source is always Scripted lesson. The browser keeps up to 80 events.

Field

Type / rule

Meaning

clock

number 0–100,000

Simulated hours; time condition is due at 24.

threshold

number 0–100

Sample score; condition is met at 80.

eligible / signal / duplicate

boolean

Business eligibility, lesson signal and duplicate replay condition.

approved

boolean | null

Trigger-specific learner approval.

dependency

enum

pending, complete or failed upstream task.

Field

Type / rule

Meaning

repo

string

Repository URL, local sample label, or saved baseline identity.

revision

string

Git commit SHA for public inspection; local samples are explicitly unverified.

inspectedAt

ISO date-time string

When this report was generated, not the repository’s last modification date.

files / totalFiles

string[] / number

Sampled paths and listed file count. Truncated GitHub trees make totalFiles a lower bound.

partial

boolean

Signals limited coverage; current inspections are partial.

findings

Finding[]

Static signals for Interface, Agent, Jev, Triggers, Memory and Harness controls.

Finding.layer / status

string / enum

Layer name; Observed or Needs review. Observed means a pattern matched.

Finding.evidence / next

string

Path, line and short excerpt; recommended next verification.

limits

string[]

Coverage warnings and explicit audit limitations.

SourceFile.path / content

string

Temporary raw input for inspection; raw file arrays are not saved in browser storage by this workflow.

Field

Type / rule

Meaning

repo / goal / notes

string

Saved framework inputs. Goal ≤500 characters; notes ≤1,500; repo ≤200.

report

RepoReport | null

Saved static inventory used to build the brief.

Message.id / role / content

string / enum / string

Local conversation message; role is user or assistant.

voice / scripted / streaming / stopped

optional boolean

Message origin and presentation state.

tool

optional string

Displayed operation receipt.

portable brief

Markdown string

Goal, review date, source revision, findings, notes and next-session instructions. Copying shares it only where you paste it.

Field

Type / rule

Meaning

state

string 10–10,000

Request task sent to TypeSafe.

model

string

Provider-returned model identity. Default request model is jev-latest unless configured.

answers.route.type / choice

choice / enum

Recommended route: code, jev, reasoning or review.

confidence

number 0–1

Provider confidence; not proof of correctness.

probabilities

record of 4 numbers

One 0–1 value per route; sum must be within 0.02 of 1.

latencyMs

number

Elapsed server time around the provider request.

mode / executed

shadow / false

No recommended operation is executed.

policy / thresholdNote

string

Review suggestion and explanation of the illustrative 0.85 threshold.

usage

optional unknown

Provider payload; no normalized cost calculation is implemented.

Field

Type / rule

Meaning

id

TEXT primary key

Composite user + request kind + minute bucket; daily IDs include day and a UTC epoch-day bucket.

count

INTEGER NOT NULL

Incremented request count, including attempts that may later fail. Chat: 15/minute, 200/day. Voice: 3/minute, 20/day. Repo and Jev: each 6/minute, 100/day. Guests additionally have daily network/site limits: chat 40/200, voice 6/20, repo and Jev each 20/100.

Field

Type / rule

Meaning

id

TEXT primary key

Voice session identifier.

user_id

TEXT NOT NULL

Authenticated workspace user; usage updates require the same user.

created_at

INTEGER NOT NULL

Creation timestamp in Unix milliseconds.

closed_at

nullable INTEGER

Last close-report timestamp in Unix milliseconds.

usage

nullable TEXT

Serialized JSON receipt; client close reports are labeled client_session_closed and are not billing proof.

finalized

INTEGER NOT NULL, default 0

0 = open/unfinalized; 1 = final. Finalized rows are not updated by the usage endpoint.

Key terms

Agent

The model-driven worker that reasons and explains.

Harness

Application code surrounding the model: context, tools, permissions, limits and checks.

Jev

Optional model for a bounded judgment; code interprets its answer.

Trigger

The condition or event that starts work.

Memory

Stored information; context is the selected information supplied for a turn.

Tool

An allowed operation with validated inputs and a result.

Shadow mode

Observe a recommendation without executing it.

Evidence

A source or result supporting a claim; its scope and date matter.