Skip to content

quickstart.md

Latest commit

 

History

History
214 lines (152 loc) · 4.92 KB

quickstart.md

File metadata and controls

214 lines (152 loc) · 4.92 KB

Policy Kit Quickstart

PEAC Policy Kit lets you define access policies for AI agents in a simple YAML file, then compile them into deployable artifacts that crawlers and agents can discover.

Flow: peac-policy.yaml -> validate -> generate -> deploy artifacts

Install

# From the PEAC monorepo
pnpm add @peac/cli

# Or use directly from the repo
pnpm --filter @peac/cli build

Quick Start

1. Initialize a Policy File

peac policy init

This creates peac-policy.yaml with a minimal open policy.

2. Edit Your Policy

# peac-policy.yaml
version: 'peac-policy/0.1'

defaults:
  decision: allow # or "deny" for restrictive default

rules:
  - name: block-training
    purpose: train
    decision: deny

  - name: allow-search-bots
    subject:
      type: agent
      labels: [search-bot]
    purpose: [crawl, index]
    decision: allow

3. Validate the Policy

peac policy validate peac-policy.yaml

# Verbose output
peac policy validate peac-policy.yaml --verbose

4. Preview Generated Artifacts

peac policy generate peac-policy.yaml --well-known --dry-run

This shows what would be generated without writing files.

5. Generate Artifacts

peac policy generate peac-policy.yaml --well-known --out dist/peac

6. Deploy

Copy the generated files to your web server:

cp dist/peac/.well-known/peac.txt /.well-known/peac.txt

Generated Artifacts

File Purpose Deploy To
.well-known/peac.txt Authoritative policy signal /.well-known/peac.txt
robots-ai-snippet.txt Robots.txt additions Append to /robots.txt
aipref-headers.json AIPREF-compatible headers HTTP middleware
ai-policy.md Human-readable summary Documentation

Note: peac.txt is the source of truth. Other artifacts are for compatibility.

Common Recipes

Open Policy (Allow Everything)

version: 'peac-policy/0.1'
defaults:
  decision: allow
rules: []

Generated peac.txt:

version: 0.9
usage: open
receipts: optional

Conditional Policy (Deny by Default)

version: 'peac-policy/0.1'
defaults:
  decision: deny

rules:
  - name: allow-search
    purpose: [crawl, index, search]
    decision: allow

  - name: allow-inference-with-receipt
    purpose: inference
    decision: allow

Generated peac.txt:

version: 0.9
usage: conditional
purposes: [crawl, index, inference, search]
receipts: required

Require Receipts

peac policy generate peac-policy.yaml --receipts required

Or override in the command:

peac policy generate peac-policy.yaml --receipts optional
peac policy generate peac-policy.yaml --receipts omit

Add Rate Limiting

peac policy generate peac-policy.yaml --rate-limit "100/hour"

Add Negotiation URL

peac policy generate peac-policy.yaml --negotiate "https://example.com/negotiate"

Add Contact Info

peac policy generate peac-policy.yaml --contact "licensing@example.com"

Debugging

Explain a Specific Rule Match

# What decision applies for an agent doing training?
peac policy explain peac-policy.yaml --subject-type agent --purpose train

# What about a human doing inference?
peac policy explain peac-policy.yaml --subject-type human --purpose inference

Common Validation Errors

Error Cause Fix
Invalid version Missing or wrong version field Use version: "peac-policy/0.1"
Unknown purpose Typo in purpose name Use: crawl, index, train, inference, ai_input, ai_index, search
Duplicate rule name Two rules with same name Use unique names for each rule

What --dry-run Shows

=== DRY RUN ===
Would write: dist/peac/.well-known/peac.txt
---
version: 0.9
usage: conditional
purposes: [crawl, index, train]
receipts: required
---

Would write: dist/peac/robots-ai-snippet.txt
...

Safety Notes

  1. Rule order matters - First matching rule wins (like firewall rules)
  2. Robots snippet is conservative - Review before appending to robots.txt
  3. AIPREF output is for compatibility - peac.txt is the authoritative source
  4. Test with --dry-run first - Always preview before writing files

Next Steps