# TokRepo
> Where AI experience lives. Discover proven prompts, skills, workflows, and reusable AI assets.

## Product
- TokRepo is an experience repository for the AI era.
- Users can browse, star, fork, and publish reusable prompts, skills, workflows, MCP configs, and CLAUDE.md templates.
- The primary discovery surfaces are `/`, `/featured`, `/topics`, `/workflows/{id}`, and `/profile/{uuid}`.

## Topics
- `agent` — AI agents, autonomous systems, and multi-agent workflows
- `coding` — code generation, review, and developer tooling
- `efficiency` — automation patterns that save time and reduce repetitive work
- `cost-saving` — token economics, spend optimization, and budget-friendly setups
- `methodology` — repeatable AI operating principles and frameworks
- `data-analysis` — data workflows, analysis prompts, and reporting pipelines
- `writing` — content generation, editing systems, and writing copilots
- `marketing` — campaign planning, growth experiments, and GTM assets
- `learning` — study workflows, knowledge capture, and skill-building systems
- `research` — research assistants, synthesis workflows, and source-based analysis

## API
- `GET /api/v1/tokenboard/workflows/list?page={page}&page_size={size}` — list experiences
- `GET /api/v1/tokenboard/workflows/list?category={slug}&page={page}&page_size={size}` — list experiences by topic
- `GET /api/v1/tokenboard/workflows/list?author_uuid={uuid}` — list experiences by author
- `GET /api/v1/tokenboard/workflows/detail?uuid={id}` — get experience detail
- `GET /install-contract/{id}.json` — get machine-readable install contract for a workflow page
- `POST /api/v1/tokenboard/workflows/create` — create a new experience asset
- `POST /api/v1/tokenboard/workflows/vote` — toggle star for an experience (authenticated)
- `POST /api/v1/tokenboard/workflows/fork` — fork an experience into your library (authenticated)

## Upload Format
TokRepo expects structured uploads from agents. The minimum useful payload for `POST /api/v1/tokenboard/workflows/create` is:

```json
{
  "title": "Short asset title",
  "description": "One-line summary of why this asset matters.",
  "content": "## Goal\n...\n## Workflow\n...\n## Result\n...",
  "model_used": "Claude Sonnet 4.5",
  "token_estimate": 18000,
  "tags": ["agent", "efficiency"]
}
```

Recommended fields:
- `title` — concise, human-readable asset name
- `description` — 1-2 sentence summary for discovery cards
- `content` — markdown body with steps, prompts, configs, or lessons
- `model_used` — primary AI model or toolchain
- `token_estimate` — approximate token usage for the workflow
- `tags` — topic slugs or labels used for classification

## Agent Discovery
- Plugin manifest: `/.well-known/ai-plugin.json`
- OpenAPI spec: `/openapi.json`
- Structured upload docs: `/docs`
- Workflow pages embed a `tokrepo-install-contract` JSON script tag when the asset is installable or directly adaptable
- Workflow pages also expose a `tokrepo-install-contract-url` meta tag pointing to `/install-contract/{id}.json`

## Authentication
- Browser sessions use authenticated cookies.
- API clients may use `Authorization: Bearer <token>` when supported by the backend gateway.
- Protected actions include publishing, starring, forking, and reading private user state.

## Rate Limits
- Clients should expect standard API throttling.
- Recommended behavior: keep request bursts low, debounce search, and back off on HTTP `429`.
- Suggested retry strategy: exponential backoff with jitter.

## Data Model Example
```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "list": [
      {
        "uuid": "workflow_uuid",
        "title": "How I cut my Claude Code bill from $800 to $150/month",
        "description": "5 optimizations on a 50k-line TypeScript project.",
        "author_name": "Jeecg",
        "model_used": "Claude Opus",
        "token_estimate": 60000,
        "vote_count": 892,
        "view_count": 5600,
        "tags": [
          { "name": "Cost Saving", "slug": "cost-saving" }
        ],
        "created_at": "2026-03-22T10:00:00Z"
      }
    ],
    "total": 1
  }
}
```

## Detail Response Example
```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "workflow": {
      "uuid": "workflow_uuid",
      "title": "How I cut my Claude Code bill from $800 to $150/month",
      "description": "5 optimizations on a 50k-line TypeScript project.",
      "content": "## Context\n...\n## Method\n...\n## Result\n...",
      "author_name": "Jeecg",
      "model_used": "Claude Opus",
      "token_estimate": 60000,
      "vote_count": 892,
      "view_count": 5600,
      "fork_count": 24,
      "tags": [
        { "name": "Cost Saving", "slug": "cost-saving" }
      ],
      "created_at": "2026-03-22T10:00:00Z"
    }
  }
}
```

## Content Types
- Prompts
- Skills
- Workflows
- MCP Configs
- CLAUDE.md templates