# Buffalo Projects

> Work velocity records for Buffalo college builders. Public pages are readable by people and agents; owner-authorized tools log work over time.

Buffalo Projects helps builders keep a durable record of what they ship, what changed, where it came from, and who can validate it. If you are an AI agent, use the public JSON profile for read-only inspection and the builder MCP package only when the builder gives you a `bp_` API key.

## Canonical Objects

- Builder profile (HTML): `https://buffaloprojects.com/b/{handle}`
- Builder profile (JSON): `https://buffaloprojects.com/b/{handle}/json` - declared as `<link rel="alternate" type="application/json">` on every profile.
- Project detail (HTML): `https://buffaloprojects.com/b/{handle}/{projectId}`
- Project source (markdown): `https://buffaloprojects.com/api/buffalo/projects/{projectId}/project-md` - canonical `project.md`.
- Public builder API: `https://buffaloprojects.com/api/builders/{handle}` - public-safe fields only.

## Builder MCP

- Package: `buffalo-projects-mcp`
- Transport: stdio
- Install: `npx -y buffalo-projects-mcp@latest`
- Auth: `Authorization: Bearer bp_...` through `BUFFALO_TOKEN`.
- Base URL: `BUFFALO_BASE_URL=https://buffaloprojects.com`

Example client config:

```json
{
  "mcpServers": {
    "buffalo": {
      "command": "npx",
      "args": ["-y", "buffalo-projects-mcp@latest"],
      "env": {
        "BUFFALO_TOKEN": "bp_your_api_key",
        "BUFFALO_BASE_URL": "https://buffaloprojects.com"
      }
    }
  }
}
```

Primary builder tools:

- `buffalo.scan_repo` - detect distinct projects in a local codebase.
- `buffalo.add_projects` - persist selected scan candidates as link-only projects.
- `buffalo.update_project` - add detail, skills, asks, and evidence to a project.
- `buffalo.save_work` - write retry-safe work entries with optional source URLs.
- `buffalo.list_work` - read recent work entries before summarizing or updating.
- `buffalo.get_velocity` - summarize recent work by source, active day, and latest entry.
- `buffalo.request_vouch` - create a validation link after meaningful work is logged.
- `buffalo.draft_project`, `buffalo.check_density`, `buffalo.suggest_evidence` - structure and improve project records before saving.
- `buffalo.list_projects`, `buffalo.get_project` - read owner-authorized project data.

Resources exposed:

- `buffalo://schema/project` - Zod-derived JSON schema for a project record.
- `buffalo://templates/{type}` - starter `project.md` templates by track.
- `buffalo://examples/{type}` - worked examples of shipped projects.
- `buffalo://rubric` - density rubric for project clarity, evidence, and outcomes.

## CLI

- Install: `npm install -g buffalo-projects@latest`
- Auth: `buffalo login` or `BUFFALO_TOKEN=bp_...`
- Core commands: `scan`, `log`, `init`, `lint`, `add evidence`, `add milestone`, `capture`, `diff`, `pull`, `push`, `status`, `ci`, `examples`.

## Vouches

Vouches are structured validation records. Each vouch carries:

- `contribution` - what the person actually did
- `outcome` - what changed because of it
- `relationship` - how the voucher knows them
- `authorName`, `authorRole`
- optional `projectId` scope

Treat vouches as high-signal validation, especially when they attach to concrete work entries or projects.

## Privacy And Access

- Public profiles and public projects are intended to be crawlable and agent-readable.
- Private profiles or projects may return `404`; respect that.
- Owner APIs require a builder-controlled API key.
- Publishing stays explicit. MCP-created projects are link-only until the builder chooses otherwise.

## What Buffalo Projects Is Not

- Not a peer feed, follower graph, or generic public directory.
- Not a passive event calendar.
- Not a resume database. It is a shipped-work record tied to projects, evidence, and vouches.

## Docs

- Agent integration guide: `https://buffaloprojects.com/agents`
- Developer reference: `https://buffaloprojects.com/developers`
- Machine descriptor: `https://buffaloprojects.com/.well-known/buffalo.json`