### Start Emulate Services via CLI

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/emulate-seed.mdx

Run the 'emulate' command to start all services with default configurations. This is the quickest way to get started.

```bash
npx emulate
```

--------------------------------

### Initialize shadcn/ui

Source: https://github.com/yonatangross/orchestkit/blob/main/src/skills/ui-components/checklists/shadcn-setup.md

Run this command to start the shadcn/ui setup process. It will guide you through selecting a style, base color, and configuring CSS variables.

```bash
npx shadcn@latest init
```

--------------------------------

### Install and Run Emulate CLI

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/emulate-seed.mdx

Install the Emulate CLI and run it to start all services or specific services with seed data. You can also generate a starter configuration file.

```bash
# Install (packages published under @emulators/* scope)
npm install --save-dev emulate

# Start all services
npx emulate

# Start specific services with seed data
npx emulate --service github,stripe --seed ./emulate.config.yaml

# Generate a starter config
npx emulate init --service github
```

--------------------------------

### Start GitHub and Vercel Services

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/emulate-seed.mdx

Use this command to start both the GitHub and Vercel emulation services concurrently. Specify the seed configuration file for setup.

```bash
npx emulate --service github,vercel --seed ./emulate.config.yaml
```

--------------------------------

### Quick Start Verify Commands

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/verify.mdx

These examples show how to quickly invoke the verify command for different scopes or models.

```bash
/ork:verify authentication flow
```

```bash
/ork:verify --model=opus user profile feature
```

```bash
/ork:verify --scope=backend database migrations
```

--------------------------------

### Multi-step Wizard for Complex Setup Flows

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/interaction-patterns.mdx

Implements a multi-step wizard pattern for guiding users through complex setup processes, showing progress and allowing navigation between steps.

```tsx
function OnboardingWizard() {
  const [step, setStep] = useState(1)

  return (
    <div role="group" aria-label={`Step ${step} of 3`}>
      <nav aria-label="Progress">
        <ol className="flex gap-2">
          {[1, 2, 3].map((s) => (
            <li key={s} aria-current={s === step ? "step" : undefined}>
              Step {s}
            </li>
          ))}
        </ol>
      </nav>
      {step === 1 && <BasicInfoStep />}
      {step === 2 && <PreferencesStep />}
      {step === 3 && <ReviewStep />}
    </div>
  )
}
```

--------------------------------

### Interview Guide Concept Testing Setup

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/product-frameworks.mdx

Use this script to introduce a prototype or concept, setting expectations for honest feedback.

```markdown
"I'm going to show you something we're working on.
It's an early concept, so don't worry about polish.
I want to hear your honest reaction."
```

--------------------------------

### Install OrchestKit Plugin

Source: https://github.com/yonatangross/orchestkit/blob/main/README.md

Use these commands to add the OrchestKit plugin to your environment. The setup wizard then personalizes your onboarding experience.

```bash
/plugin marketplace add yonatangross/orchestkit
/plugin install ork
```

```bash
/ork:setup
```

--------------------------------

### Discover and Install Skills

Source: https://github.com/yonatangross/orchestkit/blob/main/src/skills/browser-tools/SKILL.md

Discover and install capability packs on-demand using `skills list` and `skills get`. The hook treats first-party skills as trusted and warns about arbitrary third-party skill fetches.

```bash
agent-browser skills list/get <name>
```

--------------------------------

### Migration Example: Span and Generation Start

Source: https://github.com/yonatangross/orchestkit/blob/main/src/skills/monitoring-observability/references/migration-v2-v3.md

Demonstrates the migration from v3's `start_span` and `start_generation` to v4's `start_observation` with the `as_type` parameter.

```APIDOC
## Migration Example: Span and Generation Start

This example shows how to migrate from v3 to v4 for starting spans and generations.

```python
# ❌ v3 (DEPRECATED)
from langfuse import Langfuse
langfuse = Langfuse()
root = langfuse.start_span(name="pipeline")
gen = root.start_generation(name="llm_call", model="claude-sonnet-4-6")
gen.end(output=response)
root.end()

# ✅ v4 (CURRENT)
from langfuse import Langfuse
langfuse = Langfuse()
root = langfuse.start_observation(name="pipeline", as_type="span")
gen = root.start_observation(name="llm_call", as_type="generation", model="claude-sonnet-4-6")
gen.end(output=response)
root.end()
```
```

--------------------------------

### Browser Setup (Storybook/Dev)

Source: https://github.com/yonatangross/orchestkit/blob/main/plugins/ork/skills/testing-unit/references/msw-2x-api.md

Details how to set up the MSW mock worker for browser environments, suitable for Storybook or development. It includes worker initialization and starting the worker with specified unhandled request behavior.

```APIDOC
## Browser Setup (Storybook/Dev)

```typescript
// src/mocks/browser.ts
import { setupWorker } from 'msw/browser';
import { handlers } from './handlers';

export const worker = setupWorker(...handlers);

// Start in development
if (process.env.NODE_ENV === 'development') {
  worker.start({
    onUnhandledRequest: 'bypass',
  });
}
```
```

--------------------------------

### Quick Start Implementations

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/implement.mdx

These examples demonstrate how to quickly invoke the implement skill for common feature requests like user authentication, real-time notifications with a specific model, and dashboard analytics.

```bash
/ork:implement user authentication
```

```bash
/ork:implement --model=opus real-time notifications
```

```bash
/ork:implement dashboard analytics
```

--------------------------------

### Example of a Structured README

Source: https://github.com/yonatangross/orchestkit/blob/main/plugins/ork/skills/documentation-patterns/rules/docs-readme-structure.md

A comprehensive example of a well-structured README file, including sections for Quick Start, Installation, Usage, API Reference, Configuration, Contributing, and License.

```markdown
# Project Name

Brief description of what the project does and why it exists (1-2 sentences).

## Quick Start

Minimal steps to get running (copy-paste ready):

  git clone https://github.com/org/project.git
  cd project
  npm install
  npm start

## Installation

### Prerequisites
- Node.js >= 20
- PostgreSQL 16+

### Steps
1. Clone the repository
2. Copy `.env.example` to `.env` and configure
3. Run `npm install`
4. Run `npm run db:migrate`

## Usage

Common use cases with runnable code examples:

  import { createClient } from 'project';
  const client = createClient({ apiKey: process.env.API_KEY });
  const result = await client.process(data);

## API Reference

Link to generated docs or inline the key endpoints/functions.

## Configuration

| Variable |
|----------|
| `PORT` | Server port | `3000` |
| `DATABASE_URL` | PostgreSQL connection string | Required |
| `LOG_LEVEL` | Logging verbosity | `info` |

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feat/my-feature`)
3. Commit changes (`git commit -m 'feat: add feature'`)
4. Push to branch (`git push origin feat/my-feature`)
5. Open a Pull Request

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

## License

MIT -- see [LICENSE](LICENSE) for details.
```

--------------------------------

### Emulate Seed Configuration Example

Source: https://github.com/yonatangross/orchestkit/blob/main/src/skills/emulate-seed/SKILL.md

This YAML configuration pre-populates the emulator with various resources. It includes GitHub tokens and users, Vercel users and projects, Okta users, groups, apps, and authorization servers, Resend domains and API keys, Stripe customers, products, and prices, and MongoDB Atlas projects, clusters, and database users. This allows tests to start from a known state.

```yaml
# emulate.config.yaml
tokens:
  dev_token:
    login: yonatangross
    scopes: [repo, workflow, admin:org]
  ci_token:
    login: ci-bot
    scopes: [repo]

github:
  users:
    - login: yonatangross
      name: Yonatan Gross
    - login: ci-bot
      name: CI Bot
  repos:
    - owner: yonatangross
      name: my-project
      private: false
      default_branch: main
      topics: [typescript, testing]

vercel:
  users:
    - username: yonatangross
      email: yonaigross@gmail.com
  projects:
    - name: my-docs
      framework: next

# NEW in 0.4.x — drop-in seed blocks
okta:
  users:
    - login: alice@example.com
      firstName: Alice
      lastName: Smith
  groups: [{ name: Everyone }, { name: Admins }]
  apps: [{ name: My Web App }]
  authorization_servers:
    - name: default
      audiences: ["api://default"]

resend:
  domains: [{ name: example.com }]
  api_keys: [{ name: default }]
  # In tests: GET http://localhost:4009/inbox to assert captured emails

stripe:
  customers:
    - name: Test Customer
      email: customer@example.com
  products: [{ name: Pro Plan }, { name: Starter Plan }]
  prices:
    - { product: Pro Plan, unit_amount: 4900, currency: usd, recurring: { interval: month } }
    - { product: Starter Plan, unit_amount: 1900, currency: usd, recurring: { interval: month } }
  # Webhook delivery fires on checkout.session.completed / expired

mongoatlas:
  projects: [{ name: my-project }]
  clusters: [{ project: my-project, name: my-cluster }]
  database_users: [{ project: my-project, username: app-user }]

```

--------------------------------

### Install prometheus-client

Source: https://github.com/yonatangross/orchestkit/blob/main/src/skills/monitoring-observability/checklists/monitoring-implementation-checklist.md

Install the prometheus-client library using pip. Add it to your project's requirements.txt.

```bash
pip install prometheus-client
```

--------------------------------

### Basic Emulate Setup

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/emulate-seed.mdx

Demonstrates how to create a single emulator instance for a service like GitHub, configure its port and seed file, and interact with its API. Includes cleanup steps.

```typescript
import { createEmulate } from '@emulators/emulate'

const github = await createEmulate({
  service: 'github',
  port: 4001,
  seed: './emulate.config.yaml'  // Optional seed file
})

console.log(github.url) // 'http://localhost:4001'

// Use the emulated API
const res = await fetch(`${github.url}/repos/org/repo`)
const repo = await res.json()

// Cleanup
github.reset()       // Synchronous — wipes all state, keeps server running
await github.close() // Async — shuts down server and frees port
```

--------------------------------

### Development Setup and Commands

Source: https://github.com/yonatangross/orchestkit/blob/main/packages/hook-contract-py/README.md

Set up a virtual environment, install development dependencies, and run tests. Use codegen scripts to regenerate from the spec and check for drift.

```bash
cd packages/hook-contract-py
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -v
python scripts/codegen-py.py --check   # drift gate
python scripts/codegen-py.py           # regenerate from spec
mypy src/
ruff check src/ tests/

```

--------------------------------

### Install and Start Portless Proxy

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/portless.mdx

Install Portless globally and start the proxy service. The proxy can also auto-start when running an application.

```bash
# Install globally
npm install -g portless

# Start the proxy (once, no sudo needed)
portless proxy start

# Run your app (auto-starts the proxy if needed)
portless run next dev
# -> http://<project>.localhost:1355

# Or with an explicit name
portless myapp next dev
# -> http://myapp.localhost:1355
```

--------------------------------

### Install prom-client for Node.js

Source: https://github.com/yonatangross/orchestkit/blob/main/src/skills/monitoring-observability/checklists/monitoring-implementation-checklist.md

Install the prom-client library for Node.js using npm. Add it to your project's package.json.

```bash
npm install prom-client
```

--------------------------------

### Get Session Timestamps using jq

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/analytics.mdx

These jq queries extract the start and end timestamps of a session. The first command gets the timestamp of the first line (session start), and the second command gets the timestamp of the last line (session end).

```jq
# Get start/end timestamps
jq -r '.timestamp' "$SESSION_FILE" | head -1   # start
jq -r '.timestamp' "$SESSION_FILE" | tail -1   # end
```

--------------------------------

### Correct Active Documentation Example

Source: https://github.com/yonatangross/orchestkit/blob/main/src/skills/documentation-patterns/rules/docs-writing-style.md

This example shows how to write clear, scannable documentation using active voice, bullet points for steps, and a direct call to action.

```markdown
## Authentication

The API uses JWT Bearer tokens. Include the token in the
`Authorization` header of every request to a protected endpoint.

**Token lifecycle:**
1. Call `POST /auth/login` with credentials to get an access token
2. Include `Authorization: Bearer <token>` in subsequent requests
3. Tokens expire after 24 hours
4. Call `POST /auth/refresh` with the refresh token before expiry

**Example:**
  curl -H "Authorization: Bearer eyJhbG..." https://api.example.com/users

```

--------------------------------

### Correct README Structure Example

Source: https://github.com/yonatangross/orchestkit/blob/main/src/skills/documentation-patterns/rules/docs-readme-structure.md

A comprehensive example of a well-structured README file, including all essential sections for user onboarding and contribution.

```markdown
# Project Name

Brief description of what the project does and why it exists (1-2 sentences).

## Quick Start

Minimal steps to get running (copy-paste ready):

  git clone https://github.com/org/project.git
  cd project
  npm install
  npm start

## Installation

### Prerequisites
- Node.js >= 20
- PostgreSQL 16+

### Steps
1. Clone the repository
2. Copy `.env.example` to `.env` and configure
3. Run `npm install`
4. Run `npm run db:migrate`

## Usage

Common use cases with runnable code examples:

  import { createClient } from 'project';
  const client = createClient({ apiKey: process.env.API_KEY });
  const result = await client.process(data);

## API Reference

Link to generated docs or inline the key endpoints/functions.

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | `3000` |
| `DATABASE_URL` | PostgreSQL connection string | Required |
| `LOG_LEVEL` | Logging verbosity | `info` |

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feat/my-feature`)
3. Commit changes (`git commit -m 'feat: add feature'`)
4. Push to branch (`git push origin feat/my-feature`)

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

## License

MIT -- see [LICENSE](LICENSE) for details.

```

--------------------------------

### Generate Starter Emulate Configuration

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/emulate-seed.mdx

Use the 'emulate init' command to generate a starter configuration file for your emulation setup.

```bash
emulate init
```

--------------------------------

### Installed Plugins Count

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/doctor.mdx

Example output showing the total number of installed plugins and their breakdown by type.

```text
Installed Plugins: 1
- ork: 111 skills, 37 agents, 173 hook entries
```

--------------------------------

### External Dependencies - Agent Browser Not Installed

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/doctor.mdx

Example output when the agent-browser dependency is not installed, noting it's optional.

```text
External Dependencies:
agent-browser: NOT INSTALLED (optional — install via vercel-labs/agent-browser ≥ 0.26)
```

--------------------------------

### Start Emulate Services (CLI)

Source: https://github.com/yonatangross/orchestkit/blob/main/plugins/ork/skills/emulate-seed/references/upstream.md

Run this command to start all available services with default configurations. Use flags to customize which services start, the base port, or to specify a seed config file.

```bash
npx emulate
```

```bash
emulate --service vercel,github
```

```bash
emulate --port 3000
```

```bash
emulate --seed config.yaml
```

```bash
emulate init
```

```bash
emulate init --service vercel
```

```bash
emulate list
```

--------------------------------

### Install emulate package

Source: https://github.com/yonatangross/orchestkit/blob/main/src/skills/emulate-seed/references/upstream.md

Install the emulate package using npm for programmatic API usage.

```bash
npm install emulate
```

--------------------------------

### AskUserQuestion Prompt for Telemetry Setup

Source: https://github.com/yonatangross/orchestkit/blob/main/src/skills/setup/references/telemetry-setup.md

Use this prompt to ask the user about their telemetry setup preferences, offering options for full streaming, summary only, or skipping telemetry.

```python
AskUserQuestion(questions=[{
  "question": "Set up session telemetry?",
  "header": "Telemetry",
  "options": [
    {"label": "Full streaming (Recommended)", "description": "All 18 events stream via native HTTP + enriched summaries"},
    {"label": "Summary only", "description": "SessionEnd and worktree events only (command hooks)"},
    {"label": "Skip", "description": "No telemetry — hooks run locally only"}
  ],
  "multiSelect": false
}])
```

--------------------------------

### Analysis Started Log Event

Source: https://github.com/yonatangross/orchestkit/blob/main/plugins/ork/skills/monitoring-observability/examples/orchestkit-monitoring-dashboard.md

Example of a log event indicating the start of an analysis, including the analysis ID and content details.

```json
{
  "event": "analysis_started",
  "level": "info",
  "analysis_id": "550e8400-...",
  "url": "https://example.com/article",
  "content_type": "article"
}
```

--------------------------------

### Invoke Setup Wizard

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/setup.mdx

Use this command to initiate the full 8-phase OrchestKit setup wizard for a new project.

```bash
/ork:setup
```

--------------------------------

### Example: Attaching Media with `LangfuseMedia`

Source: https://github.com/yonatangross/orchestkit/blob/main/src/skills/monitoring-observability/references/migration-v2-v3.md

Provides an example of using `LangfuseMedia` to attach binary content, such as images, to spans.

```APIDOC
## Example: Attaching Media with `LangfuseMedia`

This example demonstrates how to attach media files to spans using `LangfuseMedia`.

```python
from langfuse.media import LangfuseMedia

media = LangfuseMedia(content_bytes=image_bytes, content_type="image/png")
get_client().update_current_span(input={"screenshot": media})
```
```

--------------------------------

### Multi-Service Setup

Source: https://github.com/yonatangross/orchestkit/blob/main/plugins/ork/skills/emulate-seed/references/sdk-patterns.md

Illustrates how to set up and manage multiple emulator instances concurrently, useful for testing interactions between different services.

```APIDOC
## Multi-Service Setup

### Description
This pattern demonstrates initializing multiple emulator instances simultaneously, for example, one for GitHub and another for Vercel. It shows how to manage them in parallel and clean them up together.

### Method
`createEmulate(options)`

### Parameters
#### Options
- **service** (string) - Required - The name of the service to emulate (e.g., 'github', 'vercel').
- **port** (number) - Optional - The port number for the emulator. Defaults vary by service.
- **seed** (string) - Optional - Path to a YAML seed configuration file.

### Request Example
```typescript
import { createEmulate } from '@emulators/emulate'

const [github, vercel] = await Promise.all([
  createEmulate({ service: 'github', port: 4001, seed: './config.yaml' }),
  createEmulate({ service: 'vercel', port: 4000, seed: './config.yaml' }),
])

// Both share the same seed config — tokens, users, projects
const ghRes = await fetch(`${github.url}/repos/org/repo`)
const vcRes = await fetch(`${vercel.url}/v9/projects`)

// Cleanup both
await Promise.all([github.close(), vercel.close()])
```

### Emulator API
- **`url`** (string): The base URL of the running emulator.
- **`reset()`**: Synchronously wipes all state and re-applies the seed config. The server stays running.
- **`close()`**: Asynchronously shuts down the server and frees the port.
```

--------------------------------

### Install @json-render/redux with npm

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/json-render-catalog.mdx

Install the necessary packages for using the Redux adapter with json-render. Use Redux Toolkit for a recommended setup.

```bash
npm install @json-render/redux @json-render/core @json-render/react redux
# or with Redux Toolkit (recommended):
npm install @json-render/redux @json-render/core @json-render/react @reduxjs/toolkit
```

--------------------------------

### Log Event: Analysis Started

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/monitoring-observability.mdx

Example of a structured log entry indicating the start of an analysis, including the analysis ID and the URL being analyzed.

```json
{
  "event": "analysis_started",
  "level": "info",
  "analysis_id": "550e8400-ứt",
  "url": "https://example.com/article",
  "content_type": "article"
}
```

--------------------------------

### Redlock Setup and Usage Example

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/distributed-systems.mdx

Demonstrates how to set up Redlock with multiple Redis instances and acquire/release locks using an async context manager.

```python
# Setup with multiple Redis instances
redis_clients = [
    redis.from_url("redis://redis1:6379"),
    redis.from_url("redis://redis2:6379"),
    redis.from_url("redis://redis3:6379"),
    redis.from_url("redis://redis4:6379"),
    redis.from_url("redis://redis5:6379"),
]

redlock = Redlock(redis_clients, RedlockConfig(
    ttl=timedelta(seconds=30),
    retry_count=3,
))


# Acquire and use lock
async def critical_operation(resource_id: str):
    result = await redlock.acquire(resource_id)

    if result.acquired:
        try:
            # Use lock for validity_time_ms
            print(f"Lock valid for {result.validity_time_ms}ms")
            await do_critical_work()
        finally:
            await redlock.release(result)
    else:
        print("Failed to acquire lock")
```

--------------------------------

### Auth Layer GET Request - Authentication Guide

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/feat--agent-readiness-orank/agent-readiness-explorer.html

Provides an authentication guide ('/auth.md') explaining that the API is public and read-only, requiring no credentials.

```javascript
{
  layer: "auth",
  meth: "GET",
  path: "/auth.md",
  pts: "+4",
  why: "Honest WorkOS-shaped walkthrough: the API is <b>public, no credentials</b>. Discover / Pick a method / Use the credential / Errors. No OAuth or Web-Bot-Auth stubs (they'd advertise a flow that doesn't exist).",
  sample: "# Authenticating with the OrchestKit API\n> public and read-only. No authentication required.\n## Discover ## Pick a method ## Use ## Errors"
}
```

--------------------------------

### Server (Node.js) Quick Start

Source: https://github.com/yonatangross/orchestkit/blob/main/plugins/ork/skills/json-render-catalog/references/upstream-mcp.md

Example of setting up a Node.js server using @json-render/mcp to create an MCP App. This includes defining a catalog and connecting to a transport.

```APIDOC
## Server (Node.js) Quick Start

```typescript
import { createMcpApp } from "@json-render/mcp";
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import fs from "node:fs";

const catalog = defineCatalog(schema, {
  components: { ...shadcnComponentDefinitions },
  actions: {},
});

const server = createMcpApp({
  name: "My App",
  version: "1.0.0",
  catalog,
  html: fs.readFileSync("dist/index.html", "utf-8"),
});

await server.connect(new StdioServerTransport());
```
```

--------------------------------

### Install and Manage Observability Dashboard

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/browser-tools.mdx

Commands to install, start, and stop the observability dashboard. The dashboard streams all session activity to port 4848 by default.

```bash
agent-browser dashboard install
```

```bash
agent-browser dashboard start
```

```bash
agent-browser open example.com
```

```bash
agent-browser dashboard stop
```

--------------------------------

### Setup New Environment with Golden Dataset

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/golden-dataset.mdx

Instructions for setting up a new development environment, including cloning the repository, setting up the database, restoring the golden dataset, and running verification tests.

```bash
# Fresh dev environment, need golden dataset

# 1. Clone repo (includes backup)
git clone https://github.com/your-org/orchestkit
cd orchestkit/backend

# 2. Setup DB
docker compose up -d postgres
alembic upgrade head

# 3. Restore golden dataset
poetry run python scripts/backup_golden_dataset.py restore

# 4. Verify
poetry run pytest tests/integration/test_retrieval_quality.py
```

--------------------------------

### Get Session Start Timestamp using jq

Source: https://github.com/yonatangross/orchestkit/blob/main/plugins/ork/skills/analytics/references/session-replay.md

Retrieves the timestamp of the first event in the session log, marking the session's start time.

```bash
# Get start/end timestamps
jq -r '.timestamp' "$SESSION_FILE" | head -1   # start
```

--------------------------------

### Running Orchestkit Dev Mode with Prerequisites

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/dev.mdx

This example shows the output when `/ork:dev` is run and all prerequisites are met. It also shows the output when a prerequisite is missing, indicating what needs to be installed and that the boot process is skipped.

```bash
$ /ork:dev
✓ portless     found
✓ agent-browser     found
✓ jq     found
[1] slug       feat-m125-lane-b

# OR with a missing prereq:
✗ portless not found.   Install: npm i -g portless

Skipping boot — install missing tools and re-run.
```

--------------------------------

### Installable Pytest Plugin with Timing

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/testing-perf.mdx

An example of an installable Pytest plugin that measures test durations and reports slow tests. Register the plugin using pytest_configure.

```python
import pytest
from datetime import datetime

class TimingPlugin:
    def __init__(self, threshold: float = 1.0):
        self.threshold = threshold
        self.slow_tests = []

    @pytest.hookimpl(hookwrapper=True)
    def pytest_runtest_call(self, item):
        start = datetime.now()
        yield
        duration = (datetime.now() - start).total_seconds()
        if duration > self.threshold:
            self.slow_tests.append((item.nodeid, duration))

    def pytest_terminal_summary(self, terminalreporter):
        if self.slow_tests:
            terminalreporter.write_sep("=", "Slow Tests Report")
            for nodeid, duration in sorted(self.slow_tests, key=lambda x: -x[1]):
                terminalreporter.write_line(f"  {duration:.2f}s - {nodeid}")

def pytest_configure(config):
    config.pluginmanager.register(TimingPlugin(threshold=1.0))
```

--------------------------------

### List All Tasks

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/task-dependency-patterns.mdx

Agent startup command to list all tasks in the system.

```json
// Agent startup: list all tasks
TaskList
```

--------------------------------

### Contributing Steps Example

Source: https://github.com/yonatangross/orchestkit/blob/main/docs/site/content/docs/reference/skills/documentation-patterns.mdx

Illustrates the standard steps for contributing to a project, as typically outlined in a README or CONTRIBUTING.md file.

```bash
git clone https://github.com/org/project.git
cd project
npm install
npm start
```

```bash
git checkout -b feat/my-feature
```

```bash
git commit -m 'feat: add feature'
```

```bash
git push origin feat/my-feature
```