# You.md Full Agent Context

> Generated full agent context. Source hash: 9452929ff682a12f0cac0aeefaa96d3a5cbfaaf479fc25c544df05f7f25152d1. CLI version: 0.12.0. Endpoints: 130 documented (17 internal/retired routes excluded). Local MCP tools: 6. Hosted MCP tools: 15. CLI commands: 39. Reference intelligence: 2026-07-10T15:32:59.217Z.

You.md is the agent brain and expertise-stack layer for the agent internet. It gives AI agents a portable public brain, private memory through scoped access, named YouStacks, a local runtime, HTTP APIs, and MCP tools so agents can start with the right context instead of asking the user to repeat themselves.

This file is the full-context companion to `/llms.txt`. Use it when an agent needs one plain-text read before choosing a docs page, API endpoint, MCP tool, or local runtime command.

## Base URLs

- Production: `https://you.md`
- Docs: `https://you.md/docs`
- Runtime installer: `https://you.md/install.sh`
- Docs reference: `https://you.md/api/v1/docs/reference`
- OpenAPI inventory: `https://you.md/api/v1/docs/openapi.json`
- MCP discovery: `https://you.md/.well-known/mcp.json`
- MCP JSON-RPC endpoint: `https://you.md/api/v1/mcp`
- Schema: `https://you.md/schema/you-md/v1.json`
- YouStacks capabilities: `https://you.md/api/v1/stacks/capabilities`
- Source repo: `https://github.com/houstongolden/youmd`
- Source repo handoff: README.md, AGENTS.md, and CLAUDE.md contain the repo-visible Agent Docs Preflight for coding agents.

## What You.md Is

You.md is easiest to understand as four layers:

1. Brain: identity, public profile, preferences, memory, projects, sources, provenance, directives, and trust rules.
2. YouStacks: named expertise packages containing skills, prompts, workflows, examples, adapter files, evals, update policy, and protected brain scopes.
3. Runtime: local `you` / `youmd` helper installed by curl or npm for CLI, MCP, sync, stack validation, and host adapters.
4. Protected API/MCP: authenticated access for private memory, project context, tokens, connected tools, and sensitive mutations.

Identity is one part of the brain. The product should not be treated as only a profile page or only an identity schema. The bigger goal is portable context plus reusable agent expertise.

## Recommended Agent Order Of Operations

When an agent receives a You.md link or works inside a You.md-enabled repo:

1. Read `/llms.txt` or this file to understand the platform surfaces.
2. If working in the source repo, read README.md, AGENTS.md, and CLAUDE.md; those files carry the generated-docs preflight and local project rules.
3. If a public profile is involved, fetch `GET /api/v1/profiles?username=<username>` or the human profile at `https://you.md/<username>`.
4. If local MCP is configured, call `whoami`.
5. For local coding agents, call `get_agent_brief` before planning. It combines identity, repo instructions, project context, active requests, open TODOs, installed skills, and recommended next moves.
6. If a stack is involved, inspect the manifest with `get_stack_manifest` or `you stack inspect --path <dir>`.
7. Route ambiguous work through `route_stack_request` or `you stack route --path <dir> "request"`.
8. Run `you stack doctor --path <dir>` before sharing, improving, publishing, or trusting a stack.
9. Mutate only the smallest durable surface: one memory, one project memory, one section, one stack file, or one visibility setting.
10. Leave an audit trail through MCP/API or project context so the next agent can resume.

## Source Repo Handoff

The public repo has its own durable handoff surfaces for coding agents:

- README.md: short "For Agents" section with live docs/API/MCP/stack URLs and release checks.
- AGENTS.md: cross-agent operating manual with an Agent Docs Preflight.
- CLAUDE.md: Claude-specific operating manual with the same Agent Docs Preflight.
- `.github/workflows/agent-docs.yml`: path-scoped CI guardrail that runs generated-docs checks when these surfaces change.
- `scripts/check-agent-doc-handoff.mjs`: marker check that prevents README, AGENTS.md, CLAUDE.md, /docs source, PRD, and architecture docs from losing required agent handoff markers or reintroducing stale stack/auth language.

Use those source files for repo-local rules. Use this generated file for platform-wide API/MCP/runtime/stack orientation.

## Public Identity And Context

Public routes are designed for agents:

```http
GET /api/v1/profiles?username=houstongolden
Accept: application/vnd.you-md.v1+json
```

Public identity endpoints:

- `GET /{username}/you.json`: Direct public brain JSON for a username (no JS required; ETag + schema Link preserved) (Public or rate-limited)
- `GET /{username}/you.txt`: Direct public brain markdown for a username (no JS required; ETag + schema Link preserved) (Public or rate-limited)
- `GET /api/v1/check-username`: Check availability (Public or rate-limited)
- `GET /api/v1/profiles`: List all profiles (no params) or get single profile (?username=xxx) (Public or rate-limited)
- `GET /api/v1/profiles/{username}/conversation`: Next.js route (Public or rate-limited)
- `POST /api/v1/profiles/{username}/conversation`: Next.js route (Public or rate-limited)

Use public profile responses for non-sensitive context: name, role, public bio, projects, preferences, public stacks, social links, schema metadata, and public agent-readable profile data.

Context links look like:

```text
https://you.md/ctx/<username>/<token>
```

Context links can include scoped private context depending on how the user created the link. Treat context-link contents as sensitive if they contain private sections, project context, or explicit trust boundaries.

## Local Runtime

Install:

```bash
curl -fsSL https://you.md/install.sh | bash
```

Core runtime commands:

```bash
you
you login
you whoami
you status
you pull
you push
you sync
you diff
you export
you preview
you mcp --json
you mcp --install codex --auto
you mcp --install claude --auto
you mcp --install cursor --auto
```

Use `you` as the primary runtime command. `youmd` remains installed as a compatibility alias for existing non-interactive scripts and older agent docs.

## CLI Commands

All 39 registered runtime commands, generated from the commander registrations in `cli/src/index.ts` (run `you <command> --help` for per-command options; namespaces like `skill`, `stack`, `memories`, and `private` take subcommands):

### AUTH

- `you login`: Authenticate with the You.md platform
- `you logout`: Clear local authentication for this machine
- `you register`: Register a new You.md identity
- `you whoami`: Show current authenticated user

### BUNDLE

- `you init`: Initialize a local .you/ identity context (interactive)
- `you build`: Compile local you.md bundle from profile/ and preferences/ files
- `you status`: Show pipeline/build status
- `you push`: Upload ~/.you/ files to you.md and publish
- `you pull`: Download your profile from you.md to ~/.you/ files
- `you sync`: Sync ~/.you/ files with you.md (pull + push)
- `you diff [v1] [v2]`: Compare bundle versions: `you diff` (local vs remote) or `you diff <v1> <v2>`
- `you export`: Export profile to you.json and/or you.md
- `you okf [subcommand] [arg]`: Open Knowledge Format - export/import/validate/health/view for portable OKF bundles (identity, skills, stacks)
- `you publish`: Push compiled bundle to the platform API

### CHAT

- `you chat`: Talk to the You agent - update your profile, add sources, ask questions
- `you memories [subcommand] [args...]`: Manage your memory brain (list, add, stats)
- `you private [subcommand] [args...]`: Manage private context (notes, links, projects)
- `you project [subcommand] [args...]`: Manage project agent context (init, list, show, memories)
- `you prompts [subcommand] [args...]`: Search, browse, and catalog your past messages across agent sessions
- `you tasks [subcommand] [args...]`: Consistent tasks across every project (project-context/tasks.json + tasks.md)
- `you brain [subcommand] [args...]`: Provenance-aware project truth catalog (scan, sync, map, adopt, propose, stage, apply, recover, validate, show)
- `you mine`: Mine local Claude Code + Codex session logs into a redacted identity corpus

### SKILLS

- `you skill [subcommand] [args...]`: Identity-aware agent skills (list, install, use, sync, inventory, init-project)
- `you stack [subcommand] [args...]`: Local YouStack manifests (inspect, doctor, smoke, capabilities, route, link, guard, eval, update, install)

### MONITORING

- `you agent [subcommand] [message...]`: Send/receive trusted-device realtime agent messages
- `you logs`: View agent activity log -- see what agents read/wrote and when
- `you agents`: List connected agents and their activity summary

### MCP

- `you mcp`: Start the You.md MCP server (identity context for Claude, Cursor, any MCP client)

### SHARING

- `you link [subcommand] [arg]`: Manage context links (create, list, revoke, preview)
- `you keys [subcommand]`: Manage API keys (list, create, revoke)
- `you add <source> <url>`: Add a source URL to local config (website, linkedin, x, blog, youtube, github)

### PREVIEW

- `you preview`: Start a local preview server

### SECURITY

- `you env [subcommand] [args...]`: encrypted .env.local secrets - local vault backup/restore + zero-knowledge cross-machine handoff

### MACHINE & SYNC

- `you doctor`: One-command health check -- auth, resident daemons, brain freshness, secret vault, synced machines, skills/stack sync
- `you machine [subcommand]`: set up a new machine with your synced skills, stacks, and agent config
- `you remote [subcommand] [args...]`: Cross-machine agents -- status (read-only) or run a whitelisted command on a synced machine
- `you orchestrate [subcommand] [args...]`: Master orchestrator -- launch/monitor/stop worker agents, or autonomously delegate a goal
- `you handoff [subcommand]`: End-of-day fleet handoff -- receipt registered work, guarded push, ff-only pull, identity/skill/context sync

### STORAGE

- `you storage [subcommand] [args...]`: Large files & media via folder.md -- setup | status | push | pull | list

## MCP

You.md has two MCP surfaces with distinct tool sets:

- Local stdio MCP through the runtime: 6 tools. This is the preferred surface for Claude Code, Codex, Cursor, and other local coding agents.
- Hosted same-origin JSON-RPC MCP at `POST /api/v1/mcp`: 15 tools, for web-capable clients.

Discovery:

```http
GET /.well-known/mcp.json
```

Generated MCP endpoints:

- `GET /.well-known/mcp.json`: MCP discovery metadata for agent clients (Public or rate-limited)
- `GET /api/v1/mcp`: MCP discovery ping and HTTP transport metadata (JSON-RPC, optional Bearer API key)
- `POST /api/v1/mcp`: JSON-RPC MCP endpoint for web-capable clients (JSON-RPC, optional Bearer API key)

List the hosted tools:

```json
{ "jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": 1 }
```

Call a public hosted tool (`get_identity` requires `username`):

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_identity",
    "arguments": { "username": "houstongolden" }
  },
  "id": 2
}
```

Hosted MCP tools (`POST /api/v1/mcp`):

- `whoami` (Bearer API key required): Return a compact ~500-char identity summary of the authenticated user: name, role, stack, tone, things to avoid, top projects, and current goal. This is the FIRST tool you should call when starting a new conversation - it gives you just enough context to orient on the user before deciding whether to pull the full identity bundle. Returns plain text, not...
- `get_agent_brief` (Bearer API key required): Return a startup brief for the authenticated user. Use immediately after whoami when starting Claude Code, Codex, Cursor, or another MCP-backed session. It combines a compact identity summary, the user's recent durable memories (rendered inline by default), installed skills, and recommended next moves so the agent can act without asking the user to re-expla...
- `get_project_brain` (Bearer API key required): Read the authenticated user's synchronized Project Brain catalog or one project detail. Returns the same safe revision, provenance, projection readiness, and conflict-aware normalized evidence envelope as the private Brain HTTP API. Read-only; never exposes raw filesystem roots or secrets.
- `propose_project_brain_update` (Bearer API key required): Persist one full, exact Project Brain proposal envelope for owner review. Supports RFC6902 descriptors/snapshots and structured unified diffs for existing text artifacts. This tool never applies filesystem changes. Requires write:brain.
- `resolve_project_brain_proposal` (Bearer API key required): Approve or deny one exact Project Brain proposal using a single-use nonce. An accepted decision returns the exact public proposal document and fresh signed local approval envelope; this tool never applies filesystem changes. Requires approve:brain.
- `get_identity` (public): Get a user's public identity bundle from you.md. Returns their structured identity: bio, projects, values, agent directives, communication preferences, and more. Use this at the start of a session to understand who you're working with.
- `ask_public_profile` (public): Ask a public-context-only question about a You.md profile. This is the MCP companion to POST /api/v1/profiles/{username}/conversation: it answers from the user's public you.json/you.txt surface, returns public field provenance, and explicitly omits private memories, loop reports, connected-app data, source snapshots, logs, and scoped grants.
- `search_profiles` (public): Search or list public profiles on you.md.
- `get_my_identity` (Bearer API key required): Get the authenticated user's full identity bundle, including private context. Requires a you.md API key passed as Bearer token in the Authorization header.
- `get_agent_stack_inventory` (Bearer API key required): Read the authenticated user's latest You.md agent-stack inventory snapshots: skill/stack counts, machine roots, You.md catalog gaps, DRY review queues, mirror clusters, provenance/source rollups, and repo snapshot files. Use to audit cross-machine skill drift and sync health without exposing secrets.
- `get_synced_brain_graph` (Bearer API key required): Return the authenticated user's canonical synced brain graph DTO for machines, skills, agent activity, vault signals, and optional portfolio/task signals. Use this instead of inventing fake liveness from local fallback text.
- `get_my_stacks` (Bearer API key required): List the YouStacks the authenticated user hosts in their own GitHub repo (from the You.md server-side mirror). Requires a you.md API key as Bearer token.
- `get_repo_file` (Bearer API key required): Read one file (e.g. you.md, you.json, or a stacks/<slug>/... file) from the authenticated user's repo via the You.md server-side mirror. Requires a you.md API key as Bearer token.
- `search_memories` (Bearer API key required): Full-text search the authenticated user's durable memories on you.md. Use this to recall specific facts, preferences, decisions, or context the user has stored - e.g. before answering a question about their past work or stated preferences. Returns one memory per line as plain text, relevance-ordered. Requires a you.md API key with the read:private scope...
- `report_skill_outcome` (Bearer API key required): Report the outcome of a skill execution for the authenticated user. Call this after running a you.md skill to feed the self-improvement telemetry loop - your success/failure data powers the `youmd skill improve` surface. Requires a you.md API key with the write:memories scope passed as Bearer token in the Authorization header.

Key local stdio MCP tools (of 6 total):

- `get_agent_brief`: Return a YouStack startup brief for local agents. Use immediately after whoami when starting Claude Code, Codex, Cursor, or another MCP-backed session. It combines compact identity, the user's recent durable memories (rendered inline by default), current repo instructions, project-context active requests, open TODOs, installed skills, and recommended next...
- `add_project_memory`: Save a memory scoped to a specific project. Unlike add_memory (which is global), project memories are stored locally in the project-context/ directory and only surface when working on that project. Use for architecture decisions, bug context, and feature-specific learnings.

## API

Generated docs:

```http
GET /api/v1/docs/reference
GET /api/v1/docs/openapi.json
```

Generated docs endpoints:

- `GET /api/v1/docs/openapi.json`: OpenAPI-style inventory generated from shipped You.md API routes (Public or rate-limited)
- `GET /api/v1/docs/reference`: Machine-readable docs manifest generated from routes and MCP tools (Public or rate-limited)
- `GET /api/v1/health`: Service health: status, schemaVersion, time + a cheap db probe (200 ok, 503 when the db probe fails) (Public or rate-limited)

Public identity:

```http
GET /api/v1/profiles
GET /api/v1/profiles?username=<username>
GET /schema/you-md/v1.json
GET /ctx/<username>/<token>
```

Schema endpoints:

- `GET /schema/you-md/v1.json`: Canonical you-md/v1 public brain JSON Schema (Public or rate-limited)

The `you-md/v1` format is an open, versioned schema: additive within v1, breaking changes ship as `you-md/v2` at a new URL. Third parties can implement it by serving a `you.json` that validates against `https://you.md/schema/you-md/v1.json` plus an optional `you.md` markdown render. Guide: https://you.md/docs#open-standard.

Authenticated user, private context, and memory endpoints use Bearer API keys:

```http
Authorization: Bearer ym_your_api_key_here
Content-Type: application/json
```

Common authenticated categories:

- Account: current user, profile, bundles, sources, API keys, publish, rollback, portrait.
- Memories: list, search, add, and manage durable memory.
- Private Context: private notes, projects, preferences, and user-controlled private sections.
- Activity: agent read/write/publish activity.
- Skills: registry and installed skill operations.

Common error recovery:

- `401`: missing, expired, invalid, or revoked API key. Re-run `you login` or rotate the key.
- `404`: profile, context token, bundle version, or local section not found.
- `409 ancestor_mismatch` (error.code): remote bundle changed since local parent hash. Pull, inspect diff, then push again.
- `413`: chat or compaction payload is too large.
- `429`: rate limit hit.
- `503`: spend cap or provider kill switch is active.

## YouStacks

YouStacks are named expertise packages. A stack can contain:

- skills
- prompts
- workflows
- examples
- docs
- smoke tests
- evals
- host adapter files
- protected brain scopes
- update policy
- improvement policy
- visibility policy

Local stack commands:

```bash
you stack inspect --path stacks/<name>
you stack doctor --path stacks/<name>
you stack smoke --path stacks/<name>
you stack capabilities --path stacks/<name>
you stack route --path stacks/<name> "review this like me before we ship"
you stack link --path stacks/<name> --hosts codex,claude,cursor --target .
```

Shared HTTP stack routes:

- `GET /api/v1/stacks/capabilities`: Shared YouStack capability contract and API/MCP threshold map (Public or rate-limited)
- `POST /api/v1/stacks/route`: Deterministically route a request against default or manifest-supplied YouStack capabilities (Public or rate-limited)

Route request example:

```json
{
  "request": "review this like me before we ship",
  "stack": {
    "slug": "founder-growth-stack",
    "name": "Founder Growth Stack",
    "domain": "growth",
    "tags": ["content", "founder-review"]
  },
  "capabilities": [
    {
      "id": "founder-review",
      "intent": "Review a plan using the user's founder taste.",
      "localOnly": true,
      "requiresAuth": false,
      "scopes": []
    }
  ]
}
```

Stack safety rules:

1. Run doctor before smoke, publish, public readiness, or self-improvement work.
2. Keep stacks private by default.
3. Publish only after redaction, smoke checks, manifest review, docs review, and owner approval.
4. Keep protected brain reads behind explicit scopes.
5. Do not copy private memory into public stack examples.
6. Sanitize cached or generated shell-facing identifiers before adapter or startup-helper use.
7. Keep repo/branch/runtime metadata local unless a hosted surface explicitly documents it.
8. If a protected or stack-aware read is not ready, return an honest readiness state such as not built, indexing, or ready.
9. Prefer a narrower retrieval fallback over a silent empty answer when richer retrieval is temporarily unavailable.

## API/MCP/Stack Documentation Standard

Every important capability should have five surfaces:

- Guide: human explanation and agent order of operations.
- API: HTTP endpoint or explicit reason no endpoint exists.
- MCP: MCP tool/resource when agents need it.
- Stack: local runtime or YouStack command when the capability belongs in a portable stack.
- Smoke: local or hosted check that proves the capability works.

Agents should prefer read-before-write and route-before-action:

1. Read public identity, project context, stack manifest, or docs reference.
2. Route through capabilities if intent is ambiguous.
3. Ask for the smallest private scope needed.
4. Apply the smallest mutation.
5. Run smoke checks before publish or handoff.

## Reference Intelligence

You.md keeps these as first-class inspiration and monitoring sources:

- GStack: https://github.com/garrytan/gstack (main @ 7c9df1c568a9; Changes since 11de390)
- GBrain: https://github.com/garrytan/gbrain (master @ a25209bbb2ba; Changes since 058f448)
- Agent Scripts: https://github.com/steipete/agent-scripts (main @ 4b81ea73571c; Changes since d6ed98c)
- The Library: https://github.com/disler/the-library (main @ 47f455cd139b; No new commits since last sync (47f455c))

The monitor writes:

```text
project-context/reference-intelligence/LATEST.md
project-context/reference-intelligence/TASKS.md
```

The generated task list is a review queue, not a mandate. Promote only patterns that make You.md simpler, more powerful, safer, or easier to start.

## Agent Starter Prompt

Use this prompt when starting a Claude Code, Codex, Cursor, or similar agent session:

```text
Read my You.md context first.

Use the fastest available path:
1. call the You.md MCP whoami tool if available
2. call get_agent_brief to load identity plus local project state
3. if you need full detail, call get_identity
4. before editing this repo, read project-context/
5. when you learn a durable preference or decision, save it back with add_memory or add_project_memory

Then continue with the actual task.
```

## Smoke Checks

Local:

```bash
npm run docs:check
npm run agent-docs:syntax
npm run agent-docs:handoff
npm run agent-docs:handoff:json
npm run agent-docs:lint
npm run llms:smoke -- --base-url https://www.you.md
npm run sync:graph:smoke
npm run sync:agent-stack:smoke
npx tsc --noEmit
you whoami
you status
you mcp --json
you stack doctor --path cli/examples/youstack-bamfstack-public
you stack smoke --path cli/examples/youstack-bamfstack-public
```

Hosted:

```bash
curl -fsSL https://you.md/llms.txt
curl -fsSL https://you.md/llms-full.txt
curl -fsSL https://you.md/.well-known/mcp.json
curl -fsSL https://you.md/api/v1/docs/reference
curl -fsSL https://you.md/api/v1/docs/openapi.json
curl -fsSL https://you.md/api/v1/stacks/capabilities
```

## Privacy And Trust

Public brain data is meant to be read by humans and agents.

Private memory, private project context, API keys, connected tools, and sensitive mutations require scoped auth, context links, API keys, local MCP access, or explicit approval.

Agents must not:

- expose private memory in public docs or public stack examples
- change public/private visibility without owner approval
- invent personal proof, credentials, or private facts
- write broad memory summaries when a small durable fact is enough
- publish stack changes without doctor/smoke/readiness checks

Agents should:

- request the smallest useful context scope
- preserve provenance and source links
- write narrow memories with stable labels
- prefer local files for inspectable stack work
- keep repo and branch identity local unless a protected hosted surface explicitly needs it
- return honest readiness state instead of bluffing a zero-result read
- leave a trail in project context or activity logs

## Telemetry

You.md collects three categories of telemetry to power the self-improving skill loop. skillEvents and skillOutcomes are owner-scoped and identifiable — linked to your account so the improvement loop can surface per-skill success rates and personalised recommendations (default on for authenticated users). consolidationRuns are per-user metadata (run date, duplicate count, archive count, review-queue size) used for consolidation health and rate limiting (default on, identifiable). fleetReports are aggregate only — containing category names and counts but never content strings, usernames, or any per-user identifier — and are published only when the cohort meets a k-anonymity threshold of at least 20 users (never identifiable). You can review all telemetry stored against your account from Settings > Privacy.

## Important Links

- Homepage: https://you.md/
- Docs: https://you.md/docs
- LLM index: https://you.md/llms.txt
- Full LLM context: https://you.md/llms-full.txt
- Install runtime: https://you.md/install.sh
- Docs reference: https://you.md/api/v1/docs/reference
- OpenAPI inventory: https://you.md/api/v1/docs/openapi.json
- MCP discovery: https://you.md/.well-known/mcp.json
- Schema: https://you.md/schema/you-md/v1.json
- YouStacks capabilities: https://you.md/api/v1/stacks/capabilities
- GitHub: https://github.com/houstongolden/youmd
- npm: https://www.npmjs.com/package/youmd