# You.md Full Agent Context

> Generated full agent context. Source hash: 7b12765b9fb266d2861eb7e94572c8e81a5f91aec99b44bc874bb4316206adc0. CLI version: 0.6.23. Endpoints: 79 documented (7 internal/retired routes excluded). Local MCP tools: 14. Hosted MCP tools: 0. CLI commands: 27. Reference intelligence: 2026-06-12T08:31:29.816Z.

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 `youmd stack inspect --path <dir>`.
7. Route ambiguous work through `route_stack_request` or `youmd stack route --path <dir> "request"`.
8. Run `youmd 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)

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
youmd login
youmd whoami
youmd status
youmd pull
youmd push
youmd sync
youmd diff
youmd export
youmd preview
youmd mcp --json
youmd mcp --install codex --auto
youmd mcp --install claude --auto
youmd mcp --install cursor --auto
```

Use `you` for the live U conversation. Use `youmd` for non-interactive commands inside coding agents.

## CLI Commands

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

### AUTH

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

### BUNDLE

- `youmd init`: Initialize a local .youmd/ identity context (interactive)
- `youmd build`: Compile local you.md bundle from profile/ and preferences/ files
- `youmd status`: Show pipeline/build status
- `youmd push`: Upload ~/.youmd/ files to you.md and publish
- `youmd pull`: Download your profile from you.md to ~/.youmd/ files
- `youmd sync`: Sync ~/.youmd/ files with you.md (pull + push)
- `youmd diff [v1] [v2]`: Compare bundle versions: `youmd diff` (local vs remote) or `youmd diff <v1> <v2>`
- `youmd export`: Export profile to you.json and/or you.md
- `youmd publish`: Push compiled bundle to the platform API

### CHAT

- `youmd chat`: Talk to the You agent - update your profile, add sources, ask questions
- `youmd memories [subcommand] [args...]`: Manage your memory brain (list, add, stats)
- `youmd private [subcommand] [args...]`: Manage private context (notes, links, projects)
- `youmd project [subcommand] [args...]`: Manage project agent context (init, list, show, memories)
- `youmd prompts [subcommand] [args...]`: Search and browse your past messages across agent sessions

### SKILLS

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

### MONITORING

- `youmd logs`: View agent activity log -- see what agents read/wrote and when
- `youmd agents`: List connected agents and their activity summary

### MCP

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

### SHARING

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

### PREVIEW

- `youmd preview`: Start a local preview server

## MCP

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

- Local stdio MCP through the runtime: 14 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`: 0 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`):

- No generated hosted MCP tools found.

Key local stdio MCP tools (of 14 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_memory`: Save a memory about the user - facts, preferences, decisions, or context learned during this conversation. Memories persist across sessions and inform ALL future agent interactions. Use proactively when you learn something important about the user (a preference, a decision, a project detail). Requires authentication.
- `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 `youmd 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
youmd stack inspect --path stacks/<name>
youmd stack doctor --path stacks/<name>
youmd stack smoke --path stacks/<name>
youmd stack capabilities --path stacks/<name>
youmd stack route --path stacks/<name> "review this like me before we ship"
youmd 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 @ a5833c413f98; No new commits since a5833c4)
- GBrain: https://github.com/garrytan/gbrain (master @ ecd6ae87722a; No new commits since ecd6ae8)
- Agent Scripts: https://github.com/steipete/agent-scripts (main @ a3026aea93b9; Changes since 831d5c3)
- The Library: https://github.com/disler/the-library (main @ 47f455cd139b; No new commits since 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 youmd 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
npx tsc --noEmit
youmd whoami
youmd status
youmd mcp --json
youmd stack doctor --path cli/examples/youstack-bamfstack-public
youmd 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