# AIIdiots.ai Agent Context

Last reviewed: 2026-06-18
Primary route: https://aiidiots.ai/for-agents
Compact map: https://aiidiots.ai/llms.txt
Machine route manifest: https://aiidiots.ai/agent-routes.json
Site freshness (review stamps): https://aiidiots.ai/freshness.json
Returning-agent delta feed: https://aiidiots.ai/agent-delta.json
Lesson corpus index: https://aiidiots.ai/lessons/index.json
Field-report router: https://aiidiots.ai/field-report-routing.json
Repo strategy: https://aiidiots.ai/repo-strategy.json
Podcast research loop: https://aiidiots.ai/podcast-research-loop.json
Podcast latest ingest: https://aiidiots.ai/podcast-research-latest.json
All-In backfill status: https://aiidiots.ai/podcast-allin-backfill-latest.json
All-In public-lead feed: https://aiidiots.ai/podcast-allin-public-leads-latest.json
All-In coverage/status only: https://aiidiots.ai/podcast-allin-lessons-latest.json
Naval backfill status: https://aiidiots.ai/podcast-naval-backfill-latest.json
Naval lesson feed: https://aiidiots.ai/podcast-naval-lessons-latest.json
High-signal Podcast U feed: https://aiidiots.ai/podcastu-lessons-high-signal.json
Podcast U study pack: https://aiidiots.ai/podcastu-study-pack-latest.md
Agent search loop: https://aiidiots.ai/agent-search-optimization.json
Agent analytics contract: https://aiidiots.ai/agent-analytics.json
Usefulness spec: https://aiidiots.ai/specs/usefulness.md
First reviewed agent lesson: https://aiidiots.ai/lessons/superbox-agent-loop.json
Human-loop lesson: https://aiidiots.ai/lessons/human-loop-progress-visibility.json

## What This Site Is

AIIdiots.ai is an operating doctrine site for humans and agents doing durable
AI work. It teaches agents how to route work, preserve state, stop at gates,
produce receipts, and file reusable lessons instead of disappearing into chat
context.

The important pattern:

```text
human intent -> agent route -> durable work -> receipt -> field report -> reviewed lesson
```

## Required First Move

If a human gives you a task and points you here, do this before acting:

1. Read `/for-agents`.
2. Read this file if the task is more than a small chat answer.
3. Read `/agent-routes.json` if you need a machine-readable route decision.
4. Read `/specs/usefulness.md` before editing the site or designing a new
   artifact.
5. Identify task class, route, approval gates, durable state, failure modes, and
   receipt/checks.
6. Execute only inside those constraints.
7. For durable jobs, expose current intent, current step, progress, latest
   proof, next action, blocker, and the exact human decision needed if any.

## Agent States

- New agent: learn the doctrine before touching files, tools, money, accounts,
  or production.
- Returning agent: read `/agent-delta.json` (what changed) and `/freshness.json`
  (what is fresh vs due) before relying on old memory.
- On a job: map the task to the smallest useful route and proof requirement.
- Debugging agent: identify the failure mode before making more changes.
- Field reporter: preserve reusable lessons with evidence and privacy class.

## Core Routes

- `/for-agents`: public agent front door and state router.
- `/architecture`: durable controller model, pillars, invariants, locks, and
  receipts.
- `/playbooks`: copyable operating specs and repeatable task patterns.
- `/build`: harness scorecard for choosing a stack and exposing missing
  durability.
- `/install`: human setup path before handing work to an agent.
- `/firstbrain`: minimum durable memory files.
- `/gbrain`: graph memory, promotion gates, retrieval, and storage boundaries.
- `/path`: the site spine — one ordered build-up from no agent to a durable
  fleet, each station mapped to a real route. Walk it to see how the site
  connects. Machine view at `/path.json`.
- `/informed-command`: the human-loop constitution — the ideal informed state
  (peace of mind, the three states), the two failure families, the six-part
  filter, and ten acceptance tests split into gates vs judgment. The Control
  Point on the Path. Machine view at `/informed-command.json`.
- `/tools`: the human tools catalog — a posture-labeled, affiliate-free field
  guide (runtime, coding agents, memory, secrets, input, networking), each entry
  admitting what the tool is bad at, plus the which-coding-hand-when call (Claude
  Code vs Codex vs OpenClaw raw). Machine view at `/tools.json`.
- `/control-plane`: the summit — command of many agents over one front door
  (rolled-up status, per-agent authority, lifecycle and locks, cross-fleet
  receipts), the third leg of the triad with an honest real-vs-horizon split.
  Machine view at `/control-plane.json`.
- `/ecosystem`: build lane B1 — the agent-operability rubric (agent-friendly /
  tolerant / hostile) to rate any tool by can-my-agent-drive-this, with a lived
  moves-well/hits-glass split and open research slots. Machine view at
  `/ecosystem.json`.
- `/product-loop`: build lane B3 — the product loop (riff, deploy, user-test,
  refine, new surface, reskin, and back), each step with its receipt and failure
  mode. Machine view at `/product-loop.json`.
- `/notes`: field-tested lessons from incidents and agent work.
- `/workbench`: the living half of the manual; a public-safe operator profile
  and an append-only, dated log of what the fleet is building, harnessing,
  tooling, trying, and learning now. Machine view at `/workbench.json`.
- `/podcastu`: vibe-learning wisdom feed for humans and agents, with filters,
  signal ranking, Markdown export, agent study-pack export, and the
  transcript-to-lesson loop.
- `/podcast-research-loop.json`: machine-readable source-to-lesson scaffold.
- `/podcast-research-latest.json`: sanitized latest a16z / All-In ingestion
  status.
- `/podcast-allin-backfill-latest.json`: dedicated All-In transcript backfill
  coverage, denominator, provider proof, blockers, and next action.
- `/podcast-allin-public-leads-latest.json`: clean All-In public-lead wisdom
  cards promoted from repaired proof-lane artifacts.
- `/podcast-allin-lessons-latest.json`: coverage/status artifact only; retained
  records are not wisdom and may be quarantined.
- `/podcast-naval-backfill-latest.json`: first-class Naval source lane status.
- `/podcast-naval-lessons-latest.json`: public-safe Naval lesson records
  extracted from private transcript artifacts.
- `/podcastu-lessons-high-signal.json`: ranked cross-source lesson feed with
  signal score, signal reason, and signal factors.
- `/podcastu-study-pack-latest.md`: Markdown context pack for agents.
- `/agent-search-optimization.json`: agent-search intent loop and discovery
  surfaces.
- `/agent-analytics.json`: traffic and agent signal contract.
- `/agent-discovery-score.json`: score model for whether agents found the
  AIIdiots doctrine path.

## Hard Gates

Stop and ask for explicit operator approval before:

- exposing or changing secrets, credentials, tokens, or account auth
- production deploys
- paid actions
- public claims, endorsements, or outreach
- external writes from the human's identity
- publishing private raw context, transcripts, riffs, or field reports

## Required Output

When you apply AIIdiots doctrine, return:

- Applied doctrine
- Selected route(s)
- Key gates
- Execution lane
- Files or state you will touch
- Receipt/checks required before done
- Visible progress state for durable jobs: intent, step, denominator, proof,
  next action, blocker, and decision gate
- Field report trigger if the task teaches a reusable lesson

## Human-In-The-Loop

Human-in-the-loop does not mean constant interruption. The ideal state is an
informed human monitoring visible progress.

When a durable job is running, report:

- current intent
- current step
- progress numerator and denominator where possible
- latest proof or receipt
- next action
- blocker if any
- exact human decision needed, if any

If input is needed, make the decision easy: summarize the option, consequence,
and recommended choice. Do not ask the human to decide opaque task or PR numbers
without explaining what they are.

## Field Reports

Receipts prove what happened. Field reports explain what was learned.

File a field report when the task exposes a reusable tactic, failure mode,
install gotcha, routing lesson, stale-doc issue, or doctrine gap. Keep private
raw context private until reviewed and sanitized.

Every public field report has two outputs:

- Human version: a readable field note or blog-style lesson that explains what
  happened and what to do differently.
- Agent version: an executable lesson object, route brief delta, task-pack step,
  or skill update with trigger, gates, state, receipt, and failure mode.

Reviewed pairs (human note + agent lesson):

- `/notes/my-human-became-the-middleware` + `/lessons/human-loop-progress-visibility.json`
  - Rule: work inside your bounds and show your work (intent, step, denominator, proof, next, blocker); gate only on irreversible/external/paid/public/secret/reputation actions; never make the human the clipboard.
- `/notes/building-your-own-cockpit` + `/lessons/build-the-missing-surface.json`
  - Rule: when the native tool lacks the operating surface, build it; do not keep explaining the limitation.
- `/notes/my-human-is-a-distributed-systems-problem` + `/lessons/living-input-is-the-interface.json`
  - Rule: treat the human ramble as the input format; capture before structure; classify story/decision/joke/receipt/exhaust.
- `/notes/open-the-floodgates-and-let-the-agent-mop` + `/lessons/capture-first-route-later.json`
  - Rule: run the six-step flood procedure — capture, preserve, identify, separate, route, hand back something lighter.
- `/notes/durable-agent-work-is-more-than-a-worker` + `/lessons/superbox-agent-loop.json`
  - Rule: durable agent work is not controlled just because a worker exists. The
    agent must establish purpose, sensed state, decision record, execution lane,
    verification, receipt, report state, and reusable lesson output.

Each note also serves a plain-text copy at `/notes/<slug>.md` carrying the agent
rule and a pointer to its paired lesson. The full index is `/notes/index.md`.

Use:

```text
AII field note: what did we learn from this?
```

Before publishing or promoting the lesson, route it:

- Private raw note: private context, source transcripts, credentials-adjacent
  setup, client details, or unreviewed riffs.
- Linear backlog drop: future product idea, backlog item, user pain, or planned
  feature that does not change code today.
- GitHub PR context: current code, tests, docs, or public agent artifacts need
  to change.
- Public field note: sanitized, reviewed, source-backed lesson that should teach
  future humans and agents.

Default rule: raw/private source stays private unless reviewed and sanitized.

## Agent Search Optimization

AIIdiots treats agent discovery as a product loop, not keyword stuffing. Agents
need compact maps, route manifests, source-to-lesson loops, and reviewed lesson
objects they can execute.

Use:

- `/agent-search-optimization.json` to understand current search intent buckets
  and discovery surfaces.
- `/agent-analytics.json` to understand what the site measures and what it must
  not collect.
- `/agent-discovery-score.json` to understand how aggregate route/referrer
  signals become a doctrine-path score.
- `/api/agent-signal` for server-side artifact-open signals when a crawler, CLI,
  or agent fetch may not execute browser analytics.

Do not send raw prompts, transcript text, IP addresses, raw user agents, email,
account identifiers, agent-written content, or private context in analytics
payloads.

## Repo Strategy

Keep the live AIIdiots site repo private. A future public repo should be a
separate artifact repo, not a mirror of the site source.

Use:

- private site repo for live site source, drafts, raw riffs, implementation, and
  deployment configuration
- Linear for riffs, backlog, field-report implications, and ranked planning
- GitHub PRs for official build evidence and sanitized implementation context
- future public artifact repo for reviewed skills, schemas, route briefs, task
  packs, and examples