# aiep-mirror

**Zero-friction `.well-known/aiep/` pipeline for any website.**

Licence: Apache 2.0  
Version: v2.1.0  
Specifications: P60, P61, P62, P63, P69, P70

---

## What it does

`aiep-mirror` converts any HTML website into a **machine-readable AIEP mirror surface** — a set of structured, cryptographically-bound JSON artefacts that AI systems, crawlers, validators, and automated agents can consume with full verifiability.

Three commands. Works with any static site generator. **Zero runtime dependencies** — pure Python 3.9+ stdlib.

---

## Quick start

### Option A — pip (recommended)

```bash
pip install aiep-mirror
# or: pipx install aiep-mirror  (isolated global install)
```

### Option B — download and install from this page

1. Download `aiep-mirror-v2.1.0.zip` below
2. Unzip it — you get a `aiep-mirror-v2.1.0/` folder
3. From inside that folder:
   ```bash
   pip install .
   ```
4. Or install the wheel directly:
   ```bash
   pip install aiep_mirror-2.1.0-py3-none-any.whl
   ```

---

## Usage

```bash
# 1. Run in your project root — creates .aiep-mirror.json
#    Prompts for your site URL if it can't auto-detect it
aiep-mirror init

# 2. Build your site (Astro, Next.js, Hugo, plain HTML…)
npm run build

# 3. Build AIEP mirror artefacts (reads .aiep-mirror.json automatically)
aiep-mirror build

# 4. Verify everything is correct
aiep-mirror verify

# 5. Check current config and last build
aiep-mirror status
```

**That's it.** Your `.well-known/aiep/` surface is ready to deploy alongside your site.

---

## Configuration (`.aiep-mirror.json`)

`aiep-mirror init` creates this file and prompts you for your site URL:

```json
{
  "site_base": "https://yourdomain.com",
  "in_dir": "./dist",
  "out_dir": ".",
  "visibility_default": "PRIVATE",
  "public_prefixes": ["/blog", "/docs"],
  "private_prefixes": ["/admin", "/account"]
}
```

| Field | Default | Meaning |
|---|---|---|
| `site_base` | — | Your deployed domain **(required)** |
| `in_dir` | `./dist` | Directory containing your HTML build output |
| `out_dir` | `.` | Root where `.well-known/` will be written |
| `visibility_default` | `PRIVATE` | Page visibility if no prefix matches |
| `public_prefixes` | `[]` | URL prefixes to mark PUBLIC |
| `private_prefixes` | `[]` | URL prefixes to mark PRIVATE (takes precedence) |

---

## Build pipeline integration

### Astro / Next.js

Add a `postbuild` script to `package.json`:

```json
{
  "scripts": {
    "build": "astro build",
    "postbuild": "aiep-mirror build"
  }
}
```

`npm run build` will now automatically generate `.well-known/aiep/` after Astro builds.

### GitHub Actions

```yaml
- uses: actions/setup-python@v5
  with:
    python-version: "3.11"
- run: pip install aiep-mirror
- run: aiep-mirror build
- run: aiep-mirror verify
```

---

## Output layout

```
.well-known/
  aiep-manifest.json            ← P61 manifest (hashed, bound)
  aiep-index.json               ← P62 site index
  aiep/
    pages/{content_hash}.json   ← P60 mirror pages (one per HTML page)
    proofs/{content_hash}.json  ← cryptographic proof bindings
    proofs/manifest.json        ← manifest proof
    mirror_policy.json          ← visibility policy record
```

---

## Deployment — CORS headers

The `.well-known/` directory must be served with `Content-Type: application/json` and `Access-Control-Allow-Origin: *`.

**Netlify** (`public/_headers`):
```
/.well-known/aiep/*
  Content-Type: application/json
  Access-Control-Allow-Origin: *
```

**Vercel** (`vercel.json`):
```json
{
  "headers": [
    {
      "source": "/.well-known/aiep/(.*)",
      "headers": [
        { "key": "Content-Type", "value": "application/json" },
        { "key": "Access-Control-Allow-Origin", "value": "*" }
      ]
    }
  ]
}
```

---

## Downloads

| File | Type | Size |
|---|---|---|
| [aiep-mirror-v2.1.0.zip](/downloads/repos/aiep-mirror-v2.1.0.zip) | Source + examples zip | 37 KB |
| [aiep_mirror-2.1.0-py3-none-any.whl](/downloads/repos/aiep_mirror-2.1.0-py3-none-any.whl) | Python wheel | 23 KB |