you.md

Getting Started

you.md gives every AI agent the context it should already have: your brain, your named expertise stacks, and the protected access layer needed for private memory or connected tools.

Web Quickstart

1. 1Sign up at you.md/sign-up -- takes 30 seconds
2. 2Pick a username and claim your profile
3. 3U builds your brain through conversation: identity, preferences, memory, projects, and trust rules
4. 4Open the shell, type /stacks to organize named expertise stacks, or /share to get a scoped context link

GitHub Sign-In

You.md supports GitHub OAuth as a zero-friction sign-up and sign-in path alongside the default email-code flow. Both methods are equally first-class; use whichever fits your workflow.

1. 1Go to you.md/sign-up (new user) or you.md/sign-in (returning user) and click continue with github
2. 2Authorize the You.md GitHub app. Requested scopes are read:user, user:email, and repo. The repo scope lets You.md create and read your private identity repo for stack sync.
3. 3New accounts land on /initialize to run the onboarding boot sequence. Returning accounts land directly on /shell.

Runtime Quickstart

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

1. 1Install the You.md runtime with the curl bootstrapper. The installer delivers the CLI, all bundled native skills, and auto-configures MCP for any detected agent host (Claude Code, Codex, Cursor). The CLI is the helper under the hood for files, MCP, smoke checks, host adapters, and sync.
2. 2Run you. U will guide login or setup if needed, then build and sync your brain.
3. 3Type /stacks in the shell or ask your agent to create a private coding, research, content, or BAMFStack-style stack.
4. 4Run you stack doctor --path stacks/<name> before an agent improves, shares, or publishes that stack.
5. 5Use you mcp --install codex --auto when the agent needs protected brain retrieval, tokens, sync, or connected tools.

Core Concepts

You.md is easiest to understand as four layers: the brain, YouStacks, the runtime, and protected API/MCP. The identity protocol still exists under the hood, but it should not be the first thing a user has to understand.

Simple Model

Protocol

The protocol is the machine-readable format underneath the brain. Users should not have to think about it first, but agents and builders can rely on it for stable JSON, markdown, context links, and schema discovery.

Open Standard: you-md/v1

you-md/v1 is an open, versioned schema for portable identity context: the structured document an AI agent reads to understand who someone is — identity, current focus, projects, values, voice, and agent-interaction preferences — before doing work for them. You.md publishes the schema as JSON Schema (draft 2020-12) and serves it publicly. Anyone can implement it; no account or permission is required.

# canonical JSON Schema for the format
GET https://you.md/schema/you-md/v1.json

# every public profile response advertises it
Link: <https://you.md/schema/you-md/v1.json>; rel="describedby"; type="application/schema+json"

Core sections of a you-md/v1 document, exactly as defined by the published schema (only schema and identity are required):

To implement the format on your own site or product:

1. 1Serve a you.json document with "schema": "you-md/v1" and an identity object, and validate it against the published schema with any JSON Schema validator.
2. 2Optionally serve a companion you.md markdown render of the same content for agents that prefer plain text.
3. 3Advertise the schema on your responses with the Link ... rel="describedby" header shown above so agents can discover and validate the format.

Brain Architecture

You.md's brain layer should be intentionally guided by GBrain: a shared, durable agent brain that can be read by many hosts without leaking the entire private life of the user. The brain is not a stack. It is the identity, memory, project context, provenance, retrieval policy, and permission layer that stacks can safely call into.

Context Surfaces

The same identity can be consumed through multiple surfaces depending on what the receiving agent supports.

API/MCP/Stack Standard

You.md docs should match the standard of the best agent-platform docs: every important capability needs a human guide, an HTTP contract, an MCP surface when agents need it, a local stack/runtime path, and a smoke check.

Reference Intelligence

You.md keeps GStack, GBrain, Agent Scripts, and The Library as local reference repos and turns upstream changes into reviewable tasks. GStack informs YouStacks: installable skills, specialist workflows, host adapters, upgrade behavior, QA/review/release loops, and local-first magic. GBrain informs the You.md brain: durable memory, retrieval, sync, provenance, privacy, and startup context. Agent Scripts and The Library sharpen the shared scripts, prompts, skills, slash commands, catalogs, and bootstrap patterns that make agent stacks easier to start and maintain.

Houston's local workspace also runs a daily reference sync automation, so upstream movement becomes a reviewed task queue instead of vague inspiration.

npm run references:sync

# outputs:
# project-context/reference-intelligence/LATEST.md
# project-context/reference-intelligence/TASKS.md

Source of Truth

Claude Code Integration

Most you.md users work inside Claude Code, Cursor, or similar AI coding tools. Here's how to use you.md directly from your coding environment.

Setup

1. 1Open a regular terminal (not inside Claude Code) and run curl -fsSL https://you.md/install.sh | bash once, then you to let U guide login, pull, or identity setup
2. 2Run you login to authenticate
3. 3Run you push to publish your profile
4. 4Now switch to Claude Code — all non-interactive commands work from here

Commands That Work Inside Claude Code

These commands are non-interactive and work perfectly in Claude Code, Cursor, Copilot, and any AI coding tool:

Recommended Workflow

The most powerful workflow: let your coding agent update your brain context as you work together.

1. 1Tell Claude Code: "add my preference for terminal-native UI to my you.md private context" — it can run you private notes append "prefers terminal-native UI"
2. 2After a coding session, tell your agent: "extract any preferences or facts about me from this conversation and save them to my you.md" — it can run you memories add commands
3. 3Edit your .you/files directly (they're just markdown) and run you push to sync
4. 4Use you sync --watch in a regular terminal to auto-push on every file save
5. 5Share your context with any new agent: you link create generates a URL you can paste into any AI conversation

Your identity stays up to date across every tool. Every agent knows who you are from the first message.

Share Your Brain

The core feature. Once your public brain is built, share it with any AI agent in seconds. The /share command works in both the web shell and the CLI.

/share Command

Type /share in either the web shell terminal or inside you on the CLI. Both generate the same copyable block:

> /share

--- BEGIN YOU.MD CONTEXT ---
name: Houston Golden
role: Founder & builder
projects: you.md, ...
values: ship fast, build in public
preferences: terminal-native, monochrome
--- END YOU.MD CONTEXT ---

[copied to clipboard]

Paste this into any AI conversation -- Claude, ChatGPT, Cursor, Copilot, or any agent. It instantly knows your bio, projects, values, and preferences.

Use /share --private to include your private layer (contact info, internal notes, sensitive preferences). Only share this with agents you trust.

Context Links

Shareable context links look like https://www.you.md/ctx/[username]/[token]. Any agent can fetch that scoped URL directly to load your context into its conversation.

Sync

You.md works across web and CLI. Create your profile on either platform and keep them in sync.

Connecting Web + CLI

The CLI uses the same email and verification-code flow as the web app -- no separate API token needed for your own account.

1. 1Create your profile on either web or CLI
2. 2you login -- press Enter to open browser sign-in, or type the same email you use on the web and paste the verification code in-terminal
3. 3you pull downloads your web profile to local files
4. 4Edit files in any editor (Cursor, Obsidian, VS Code)
5. 5you push compiles and publishes back to you.md
6. 6you sync --watch auto-syncs on every file save

Local File Structure

.you/
  profile/
    about.md
    now.md
    projects.md
    values.md
    links.md
  preferences/
    agent.md
    writing.md
  voice/
    voice.md
    voice.linkedin.md
  you.json
  you.md
  manifest.json

Sync Across Machines

You.md is designed to follow you across every machine you work on. Four distinct sync planes cover everything: your identity, your secrets, your skills, and your named stacks. Each plane uses the right transport for its sensitivity level.

Four Sync Planes

Set Up a New Machine

From the You.md dashboard, ask the shell for /new computer. It mints a short-lived bootstrap key and returns one copyable command for Claude Code or Codex on the fresh machine. Terminal-only users can generate the same runbook with you machine prompt.

# Web shell
/new computer

# CLI-only
you machine prompt --root ~/Desktop/CODE_YOU --days 30 --limit 80

# Bounded proof run before cloning the full set
you machine prompt --root /tmp/you-clean-host-CODE_YOU --days 30 --limit 80 --max-clone-projects 2

The generated command installs You.md, authenticates, pulls and syncs your identity bundle, restores shared skills/stacks/agent host config, hydrates the portfolio graph from You.md and GitHub, creates ~/Desktop/CODE_YOU, clones truly active 30-day project repos first, asks before expanding to the active 90-day project set, checks env-vault readiness, optionally lists and restores an encrypted env vault, then rehydrates local README/project-context/env-key evidence and syncs a secret-safe machine proof report. For clean-host proof runs, add --max-clone-projects or set YOU_MAX_CLONE_PROJECTS; legacy YOUMD_MAX_CLONE_PROJECTS still works. Omit it on the real new machine to clone the full selected graph-backed set.

CLI Reference

Install with curl -fsSL https://you.md/install.sh | bash as the recommended path. The curl installer delivers the full package in one step: the you CLI, all bundled native skills, and automatic MCP configuration for any detected agent host (Claude Code, Codex, Cursor). Use npm i -g youmd@latest only if you prefer to manage the binary yourself; you will need to run you mcp --install <host> --auto separately. The CLI covers the full identity lifecycle -- identity, auth, sync, sharing, memory, projects, and skills.

The 31 commands below are generated from the commander registrations in cli/src/index.ts and grouped the same way as you --help. Namespaces like skill, stack, memories, private, project, link, and keys take subcommands — run you <command> --help for per-command options, and see the skill subcommand reference for the full you skill ... surface.

Skills

Skills are brain-aware markdown templates that turn your you.md brain and stacks into actionable outputs. They use {{var}} interpolation to inject your brain data at runtime -- so the output is always personalized to you.

Overview

A skill is a .md file with template variables. When you run a skill, the CLI resolves each {{var}} against your you.json bundle and renders the final output. Skills can generate CLAUDE.md files, project scaffolding, cover letters, outreach messages, or anything else that benefits from knowing who you are.

# {{name}}'s Project Context

## Who You Are
{{bio}}

## Your Stack
{{preferences.tools}}

## Communication Style
{{voice.style}}

## Current Focus
{{now}}

Install skills from the public registry, create your own, or publish them for others. The skill system is fully local-first -- installed skills live in .you/skills/ and sync with push/pull.

CLI Commands

The you skill namespace has 18 core subcommands covering the full skill lifecycle:

Bundled Skills

Every you.md install ships with eight built-in skills. These are always available and kept in sync with CLI updates.

init-project

The you skill init-project command is the fastest way to make a repo brain-aware. It sets up four things:

1. 1AGENTS.md -- the repo-visible instruction layer with workflow rules and your generated brain context
2. 2CLAUDE.md -- the Claude-specific entrypoint with a managed You.md bootstrap block
3. 3project-context/ -- the canonical repo context directory, filled additively per file
4. 4.you/ plus host-linked skills -- the generated additive layer and tool-specific discovery surfaces

$ you skill init-project
  install claude-md-generator ready
  install project-context-init ready
  .you/ created AGENT.md, STACK-MAP.md, project-context/README.md
  agent instruction files created AGENTS.md; created CLAUDE.md
  project-context/ created TODO.md, FEATURES.md, CHANGELOG.md, PROMPTS.md ...
  link .claude/skills/youmd/ /path/to/repo/.claude/skills/youmd
  done -- your repo is brain-aware

Skill Sync

Installed skills are stored in your local .you/skills/ directory and tracked in your bundle manifest. When you run you push, your skill installs are synced to the cloud. When you run you pull on another machine, your skills come with it.

Use you skill sync to explicitly reconcile local and remote skill state without a full push/pull cycle.

YouStacks

A YouStack packages your own expertise and workflows into your own stack. Think of Gary Tan creating GStack from years of startup operating experience, specialist agents, taste, review loops, and workflows. YouStacks let anyone do that for their own domain, and you can keep multiple named stacks for different expertise lanes.

Overview

Named Stacks

A You.md account should be able to own many YouStacks. The manifest name is the human label, the slug is the stable install id, and domain, aliases, and tags make the stack discoverable by agents and humans.

youstacks/
  coding-copilot/
    youstack.json
  scientific-research/
    youstack.json
  content-studio/
    youstack.json

What Goes In

A YouStack should feel like an installable version of how you operate. The local part carries the reusable expertise. The protected part stays behind You.md auth.

Self-Improving Stacks

A strong YouStack should not be frozen promptware. Each stack and each skill inside it should have an improvement loop: observe how agents use it, catch failures, absorb user corrections, run evals, update examples, and refresh local adapter files when the manifest policy allows it.

Self-improving does not mean uncontrolled. The v1 default is: propose improvements, auto-apply only safe local file refreshes when the manifest allows it, and require approval for private context reads, brain writes, connected tools, remote repo writes, and visibility changes.

Proposals + Consent

Server-generated maintainer proposals and background analysis consent are the two human-approval gates that keep the improvement loop auditable.

Use you stack proposals to see proposals the server has generated about your stacks — skill quality improvements, doc drift, stale adapter files, or capability gaps. Review each proposal before anything changes:

Use you stack consent to control which background analyses are allowed to run on your data. Scopes are narrow and opt-in; none run automatically without your explicit grant:

Safety and Readiness Contract

The Jun 2026 reference-intelligence wave sharpened four product rules for YouStacks and the protected brain layer: shell-facing helpers must be sanitized at use time, local metadata should stay local by default, protected reads should report honest readiness, and retrieval should fall back before it goes silent.

In short: local metadata should stay local by default, protected reads should report honest readiness, and retrieval should fall back before it goes silent.

Reference Intelligence Loop

YouStacks should deliberately follow what works in GStack, GBrain, Agent Scripts, and The Library. The loop is: fetch upstream repos, inspect the newest commits, map each useful pattern to the stack layer, brain layer, docs layer, or runtime layer, then create a concrete You.md task only when it improves the product.

Use Cases

Runtime, Not CLI-First

Users should not have to understand a CLI before they understand YouStacks. The product promise is: run one curl command, then your agents can see the You.md runtime, native skills, stack manifests, auto-update helper, MCP server, and host adapters. The helper commands exist for agents and power users.

curl -fsSL https://you.md/install.sh | bash
you stack doctor --path cli/examples/youstack-personal
you stack smoke --path cli/examples/youstack-personal
you stack route --path cli/examples/youstack-personal "search my memories before starting"
you stack link --path cli/examples/youstack-personal --hosts codex --target . --dry-run

Shell And Profile Management

You.md should expose stack management in the web shell and profile the same way it exposes skills, sharing, memory, and agents. Type /stacks in the shell to view named stacks, their visibility, install command, update policy, and maintainer workflow. Public profiles can show only stacks whose manifest is public-open; private and scoped stacks stay owner-only.

Install Flow

1. 1Install the runtime once with curl -fsSL https://you.md/install.sh | bash. This installs current You.md source, bundled skills, the auto-upgrade helper, and stack diagnostics.
2. 2Pull, create, or ask U to scaffold a named stack folder that contains youstack.json, local skills, prompts, sub-agents, workflows, docs, examples, and smoke tests.
3. 3Run you stack inspect --path DIR to read metadata, declared scopes, adapters, capabilities, and warnings before trusting the package.
4. 4Run you stack smoke --path DIR. This is read-only: it validates schema, required files, checksums, adapters, and capability declarations without touching the brain.
5. 5Generate host-native files with you stack link --path DIR --hosts codex,claude,cursor --target .. Use --dry-run first when installing into an existing repo.
6. 6Start the host agent. It can read local stack files first, then use You.md MCP/API only for protected memory, private context, sync, grants, connected tools, or server-side actions.

Auto-Update

The curl installer writes a best-effort auto-upgrade helper at ~/.you/bin/youmd-auto-upgrade. Host adapter files and the youstack-maintainer skill can run it quietly before stack work, just like the BAMFStack preamble. The helper is throttled by default so it does not rebuild on every agent message.

if [ -x "$HOME/.you/bin/youmd-auto-upgrade" ]; then
  "$HOME/.you/bin/youmd-auto-upgrade" --quiet || true
fi

BAMFStack Lighthouse

BAMFStack should be the first public proof that YouStacks work: a shareable, open creator-growth stack with a one-line install, local skills, commands, workflow routing, read-only smoke checks, docs-quality examples, env-only API key handling, and protected API/MCP calls for real product actions.

you stack inspect --path cli/examples/youstack-bamfstack-public
you stack doctor --path cli/examples/youstack-bamfstack-public
you stack smoke --path cli/examples/youstack-bamfstack-public
you stack route --path cli/examples/youstack-bamfstack-public "draft a creator post from research"

Manifest

The v1 manifest is youstack.json. It declares package metadata, local files, requested brain scopes, host adapters, capabilities, access policy, sharing modes, repo sync metadata, docs, and smoke tests.

{
  "schemaVersion": "youstack/v1",
  "kind": "youstack",
  "slug": "founder-growth-stack",
  "name": "Founder Growth Stack",
  "domain": "growth",
  "aliases": ["content", "linkedin", "founder-led-growth"],
  "tags": ["content", "growth", "founder-review"],
  "version": "0.1.0",
  "visibility": "private",
  "brainScopes": [
    {
      "scope": "identity.public.read",
      "required": true,
      "reason": "Introduce the user to the host agent."
    }
  ],
  "files": [
    {
      "path": "skills/founder-review/SKILL.md",
      "type": "skill",
      "required": true
    },
    {
      "path": "subagents/operator.md",
      "type": "subagent",
      "required": true
    },
    {
      "path": "workflows/growth-writing.md",
      "type": "workflow",
      "required": true
    }
  ],
  "capabilities": [
    {
      "id": "founder-review",
      "intent": "Review a plan using the user's founder taste and operating rules.",
      "localOnly": true,
      "mutationPolicy": "read_only"
    }
  ],
  "accessPolicy": {
    "defaultMode": "local_static",
    "protectedByDefault": true
  },
  "improvement": {
    "mode": "propose",
    "cadence": "after meaningful agent sessions",
    "signals": ["usage", "failures", "user corrections", "repo diffs"],
    "evals": ["you stack smoke", "golden prompt regression checks"],
    "appliesTo": ["skills", "subagents", "workflows", "examples", "docs"],
    "approvalRequiredFor": ["brain.write", "private_context.read", "connected_tool.write", "remote_repo.write"]
  },
  "update": {
    "channel": "manual",
    "check": "you stack smoke",
    "source": "user-owned GitHub repo or local stack folder",
    "autoApply": false
  }
}

Examples

A personal stack is the closest mental model: build your own GStack from your expertise, workflows, sub-agents, examples, and taste; name separate versions for different domains; install them into the agents you already use; and let protected requests cross the You.md brain boundary only when needed.

# coding stack
you stack inspect --path stacks/coding-copilot

# scientific research stack
you stack route --path stacks/scientific-research "triage these papers and design the next experiment"

# content stack
you stack route --path stacks/content-studio "turn this idea into a LinkedIn post in my style"

# open public stack example
you stack inspect --path cli/examples/youstack-bamfstack-public
you stack doctor --path cli/examples/youstack-bamfstack-public
you stack smoke --path cli/examples/youstack-bamfstack-public

# public install surface stays curl-first
curl -fsSL https://you.md/install.sh | bash

# host agents use the maintainer skill for safe updates
you skill use youstack-maintainer

# inspect what a stack asks for
you stack inspect --path stacks/my-founder-stack

# verify it without writing adapter files
you stack smoke --path stacks/my-founder-stack

# ask the deterministic router which capability should handle a request
you stack route --path stacks/my-founder-stack "review this like me before we ship"

# link the same stack into Codex, Claude Code, and Cursor
you stack link --path stacks/my-founder-stack --hosts codex,claude,cursor --target .

A public stack can expose the reusable agent kit while protected capabilities still require authentication.

{
  "id": "review-release",
  "intent": "Run the repo release review workflow before landing changes.",
  "localOnly": true,
  "mutationPolicy": "read_only",
  "triggers": ["review", "ship", "release", "qa"],
  "entrypoint": "workflows/release-review.md"
},
{
  "id": "skill-improvement-loop",
  "intent": "Improve stack skills from failures, user corrections, eval results, and updated examples.",
  "localOnly": true,
  "mutationPolicy": "write_local",
  "entrypoint": "improvement/skill-loop.md"
},
{
  "id": "protected-memory-search",
  "intent": "Search private user memory when local files are not enough.",
  "localOnly": false,
  "requiresAuth": true,
  "scopes": ["memories.search"],
  "mutationPolicy": "read_only"
}

API/MCP Threshold

Local-only stacks can ship names, slugs, domains, static skills, sub-agents, workflows, prompts, docs, examples, evals, improvement proposals, host adapter files, and read-only route tables. Use shared You.md API/MCP when the stack needs protected brain retrieval, private context, stack grants, sync, audit logs, connected tools, or server-side actions. Custom per-stack API/MCP is optional later, not the v1 baseline.

API + MCP

The shared HTTP endpoints let products and agents inspect the default capability contract and route a request against either that default contract or manifest-supplied capabilities.

GET /api/v1/stacks/capabilities

POST /api/v1/stacks/route
Content-Type: application/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": []
    }
  ]
}

The local MCP server exposes stack-native tools so Claude Code, Codex, Cursor, and similar hosts can inspect and validate a stack before using it.

Agent Directives

Directives are instructions embedded in your you.md brain that tell AI agents how to behave when working with you. They live in your preferences layer and are included in every context share.

Unlike skills (which are templates you run), directives are passive -- they ride along with your brain and shape how agents respond to you. Think of them as persistent system prompts keyed to your preferences.

# Agent Directives

## Tone
Direct and concise. No filler. No corporate speak.

## Code Style
Prefer functional patterns. Use TypeScript strict mode.
Never add comments that restate the code.

## Workflow
Act decisively -- don't ask permission for obvious next steps.
Show progress, don't go silent.
Address every part of multi-part messages.

When an agent reads your context (via /share, a context link, or the API), your directives are included automatically. Any agent that respects your you.md will follow them.

Agent Workflows

The strongest You.md workflow is continuous context maintenance: the agent reads who you are, does the work, then saves the durable things it learned so the next agent starts smarter.

Golden Path

1. 1Orient with whoami or GET /api/v1/profiles?username=...
2. 2For local coding agents, call get_agent_brief to load identity, repo instructions, active requests, TODOs, installed skills, and the next move in one shot
3. 3Pull the full context only when needed with get_identity, a context link, or you pull
4. 4Check project context before substantial work with get_project_context or you project show
5. 5Mutate only the smallest durable layer: memory, project memory, one identity section, one skill, or one source
6. 6Compile and publish with compile_and_push or you push when the user wants the change live
7. 7Leave an activity trail through MCP/API so the user can see which agents read, wrote, or published context

Playbooks

Examples

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 + 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.

# Install the local agent surface
curl -fsSL https://you.md/install.sh | bash

# Wire MCP into an agent host
you mcp --install claude --auto
you mcp --install codex --auto
you mcp --install cursor --auto

# Smoke-test brain access
you whoami
you mcp --json

Agent Docs

You.md now exposes root-level agent docs so a coding agent can discover the platform before crawling the app. Treat /llms.txt as the short index and /llms-full.txt as the full context pack for docs, API, MCP, runtime, stack routing, and smoke checks. Both files are generated from the shipped docs reference and upstream reference-intelligence state.

Source-repo agents get the same handoff in README.md, AGENTS.md, and CLAUDE.md. Keep those files aligned with the generated root docs so GitHub, npm, local coding agents, and web-capable agents all start from the same API/MCP/stack map.

# Fast agent preflight
curl -fsSL https://you.md/llms.txt
curl -fsSL https://you.md/api/v1/docs/reference
curl -fsSL https://you.md/.well-known/mcp.json

# Full docs/context pass
curl -fsSL https://you.md/llms-full.txt

# Release smoke
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
npm run agent-docs:ci

API

You.md has a first-party HTTP API, same-origin web proxies, a JSON Schema, and MCP endpoints for agent-native access. The endpoint inventory below is generated from source on every build, so it tracks the routes that actually ship.

Public Endpoints

Public routes are intentionally agent-readable: profile JSON, markdown negotiation, schema discovery, MCP discovery, context links, auth handshakes, and rate-limited enrichment helpers.

Authenticated Endpoints

Include your API key as a Bearer token. Generate keys from the shell (/settings) or via CLI (you keys create).

Authorization: Bearer ym_your_api_key_here
Content-Type: application/json

Skills API

Programmatic access to the skill registry and your installed skills. Public endpoints are unauthenticated. Install, usage, and publish endpoints require a Bearer token.

MCP Server

You.md ships two MCP surfaces with distinct tool sets: a local stdio server through the CLI (6 tools) and a hosted same-origin JSON-RPC endpoint (12 tools) for clients that can speak HTTP. The local server is the power path for Claude Code, Codex, Cursor, and similar coding agents.

# MCP discovery — auto-configure any MCP-compatible client
GET /.well-known/mcp.json

# JSON-RPC 2.0 MCP endpoint
POST /api/v1/mcp
Content-Type: application/json

# Example: list available tools
{ "jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": 1 }

# Example: get a user's public identity (username is required)
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_identity",
    "arguments": { "username": "houstongolden" }
  },
  "id": 2
}

Hosted MCP tools — the 12 tools served by POST /api/v1/mcp. get_identity and search_profiles are public; the rest require a Bearer API key.

The local stdio server also exposes get_agent_brief, a YouStack startup brief that combines identity, repo instructions, active requests, open TODOs, installed skills, and recommended next moves for Claude Code, Codex, Cursor, and similar agents.

Configure via CLI:

npx --yes youmd@latest mcp --install claude --auto
npx --yes youmd@latest mcp --install cursor --auto
you mcp --json               # Print the exact MCP config JSON

Local stdio MCP tools — all 6 tools served by the local runtime:

Schema

Public profile responses point to the canonical you-md/v1 schema with a Link header. Agents can validate the identity document before caching or mutating it. The format itself is an open standard — see Open Standard: you-md/v1 for sections, versioning policy, and how to implement it.

GET /schema/you-md/v1.json
Accept: application/json

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

Docs Automation

Errors + Troubleshooting

You.md keeps errors plain because agents need recoverable instructions more than theatrics. HTTP endpoints return JSON with an error field, context links use explicit status codes, and bundle writes return 409 for ancestor mismatches so clients know to pull before pushing.

# Most useful smoke checks
you whoami
you status
you diff
you mcp --json
npm run docs:check

Privacy

You.md uses a two-layer privacy model:

Context links can be generated from the shell with /share or from the CLI with you link create. API keys can be created, revealed, rotated, and revoked from settings or you keys.

Telemetry & Privacy

You.md collects three categories of telemetry to power the self-improving skill loop. Each category has a distinct privacy posture:

Owner-scoped telemetry (skillEvents, skillOutcomes, consolidationRuns) is on by default and linked to your account so the improvement loop works. Fleet telemetry is anonymised before aggregation and published only when the k-anonymity threshold (k ≥ 20) is met, so no individual can be identified from a fleet report. Fleet snapshots returned to you show only fleet-wide aggregates respecting the k-anon floor of 20 — your individual usage never appears in any other user’s snapshot. You can review all telemetry stored against your account from the dashboard under Settings › Privacy.

Dashboard Commands

The web shell supports the following slash commands: