0xroylee · 0xroylee · May 8, 2026 · May 8, 2026 · May 8, 2026
diff --git a/README.md b/README.md
@@ -6,6 +6,10 @@ The purpose is simple: create an idea, task, or issue in Linear; ADHD.ai pulls t
 
 Production default: run unattended processing with `adhd-ai cron`. Use `adhd-ai run --poll` as a local/dev mode when iterating on workflow behavior.
 
+## Operator Guide
+
+For non-technical operators, start with [NON_TECHNICAL_GUIDE.md](docs/NON_TECHNICAL_GUIDE.md).
+
 ## Purpose
 
 - Use Linear as the job board for engineering ideas, tasks, and issues.

diff --git a/docs/NON_TECHNICAL_GUIDE.md b/docs/NON_TECHNICAL_GUIDE.md
@@ -0,0 +1,78 @@
+# ADHD.ai Non-Technical Guide
+
+This guide explains how to use ADHD.ai as an operator without needing to read the codebase.
+
+## What ADHD.ai Does
+
+ADHD.ai takes work tracked in Linear and moves it through an automated engineering workflow:
+
+1. planning
+2. implementation
+3. review and testing
+
+The system keeps Linear and GitHub updated as work advances.
+
+## Basic Workflow
+
+1. A person creates or assigns a Linear issue.
+2. ADHD.ai picks up eligible issues based on project routing config.
+3. A planning agent writes a concrete implementation plan.
+4. An implementation agent changes code in the target repository and updates the pull request context.
+5. A review/testing agent validates the result.
+6. If review/testing fails, ADHD.ai loops back to implementation with structured bug feedback.
+7. The issue ends as `done` or `blocked`.
+
+## How Each Integration Fits
+
+### Linear
+
+Linear is the work queue and progress tracker.
+
+- Issues are the source of truth for what should be done.
+- Status and comments are updated as stages change.
+- Complex planning outputs can be split into child issues.
+
+### GitHub
+
+GitHub is where code changes are reviewed and tracked.
+
+- ADHD.ai creates or updates branch/PR context during implementation.
+- Review/testing feedback is tied back to the same work stream.
+- PR history gives an audit trail of what changed.
+
+### Resend (Optional)
+
+Resend is used only for optional email notifications.
+
+- ADHD.ai can send terminal outcome notifications (`done` or `blocked`).
+- If Resend is not configured, the core workflow still works.
+
+### Claude and OpenAI Codex
+
+ADHD.ai runs agent stages using a configurable backend and model settings.
+
+- Planning, implementation, and review/testing can use configured models.
+- Claude/OpenAI Codex are runtime options, not both required at the same time.
+- Behavior depends on your project config and environment values.
+
+## Operator Setup and First Run
+
+1. Run `adhd-ai setup` and answer prompts.
+2. Run `adhd-ai setup --check` to validate config and required tooling.
+3. Run `bun run src/index.ts projects` to confirm project resolution.
+4. Start one scoped run: `bun run src/index.ts run --project <PROJECT_ID>`.
+5. Confirm run state appears under `.piv-loop/projects/<project-id>/runs`.
+
+More detail:
+
+- onboarding flow: [new-user-onboarding.md](product-specs/new-user-onboarding.md)
+- operations and plan contract: [PLANS.md](PLANS.md)
+- reliability behavior: [RELIABILITY.md](RELIABILITY.md)
+
+## What To Check When Work Is Blocked
+
+1. Confirm the issue is in the expected Linear status and assigned to the expected project.
+2. Check run state and errors under `.piv-loop/projects/<project-id>/`.
+3. Verify required credentials exist in environment or local secret storage.
+4. Confirm GitHub authentication and repository routing are valid.
+5. Re-run with scoped flags (`--project`, `--issue`) to isolate one workflow path.
diff --git a/docs/product-specs/index.md b/docs/product-specs/index.md
@@ -4,7 +4,8 @@ ADHD.ai turns Linear issues into staged agent execution with planning, implement
 
 ## Current Specs
 
-- [new-user-onboarding.md](/Users/roy/Desktop/SourceCode/agentic/show-me-ur-agents/docs/product-specs/new-user-onboarding.md)
+- [new-user-onboarding.md](new-user-onboarding.md)
+- [NON_TECHNICAL_GUIDE.md](../NON_TECHNICAL_GUIDE.md)
 
 ## Product Workflow Summary
 

diff --git a/skills/README.md b/skills/README.md
@@ -9,6 +9,7 @@ This directory is the default skill pack root for ADHD.ai.
 - `piv-plan/SKILL.md`
 - `piv-implement/SKILL.md`
 - `piv-review-test/SKILL.md`
+- `adhd-docs/SKILL.md`
 
 ## Configure a custom skill root
 
@@ -44,3 +45,7 @@ You can source skills from another repo in three common ways:
 3. Copy selected skill folders into this `skills/` directory.
 
 For reproducibility, pin submodules or clone to a known commit.
+
+## Included Documentation Skill
+
+`adhd-docs/SKILL.md` is for generating and maintaining plain-language, operator-facing documentation that explains workflow behavior and integrations (Linear, GitHub, optional Resend notifications, and Claude/OpenAI Codex runtime options) without exposing secrets.
diff --git a/skills/adhd-docs/SKILL.md b/skills/adhd-docs/SKILL.md
@@ -0,0 +1,37 @@
+---
+name: adhd-docs
+description: Documentation skill for producing plain-language ADHD.ai guides for non-technical operators.
+---
+
+# ADHD.ai Docs Skill
+
+You are the documentation agent for ADHD.ai.
+
+## Goals
+
+1. Explain ADHD.ai in plain language for non-technical operators.
+2. Describe how the workflow moves from Linear intake to done/blocked outcomes.
+3. Clarify how integrations are used without exposing secrets.
+4. Keep documentation short, accurate, and directly usable.
+
+## Writing Rules
+
+1. Use concrete terms and short sentences.
+2. Avoid internal implementation jargon unless it is required, and define it when used.
+3. Separate required setup from optional features.
+4. Keep operator actions explicit: what to run, what to check, what success looks like.
+
+## Integration Coverage
+
+When relevant, briefly explain:
+
+1. Linear: issue intake, routing, statuses, and progress visibility.
+2. GitHub: branch and PR lifecycle for implementation and review.
+3. Resend: optional terminal outcome email notifications.
+4. Claude/OpenAI Codex: configurable agent backend and model selection for planning, implementation, and review/testing.
+
+## Safety Constraints
+
+1. Do not include API keys, tokens, or secret examples.
+2. Do not claim integrations are mandatory when they are optional in config.
+3. If behavior depends on configuration, state that dependency clearly.