> ## Documentation Index
> Fetch the complete documentation index at: https://docs.semicola.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operating instructions and policy versions

> The versioned playbook instructions and acceptance policy your storefront agent applies, and how to read, create and reactivate versions.

Two of your storefront's rulebooks are **versioned**:

| Rulebook                   | What it holds                                                 | Edited on                                    |
| -------------------------- | ------------------------------------------------------------- | -------------------------------------------- |
| **Operating instructions** | Markdown on how to pitch, package, name and explain products. | [Playbook](/sell/playbook)                   |
| **Acceptance policy**      | Your **Brief acceptance** and **Creative policy** text.       | [AI Business Rules](/sell/ai-business-rules) |

Each save creates a new, immutable version and makes it the active one. Exactly one version is active
at a time, and only the active version steers the storefront agent. Versions are numbered per
storefront from `1` and never reused. Older versions stay in history, so you can read them or make
one active again.

## What belongs where

| Fact                                                 | Where it lives                                          |
| ---------------------------------------------------- | ------------------------------------------------------- |
| Prices, floors and target percentile                 | Playbook **pricing facts**                              |
| Discounts for a buyer's brand or operator            | Playbook **house discounts** and **buyer instructions** |
| Advertiser, category and creative eligibility        | **AI Business Rules** (acceptance policy)               |
| Whether a person reviews buys and creatives          | **AI Business Rules** approval gates                    |
| Product packaging, naming, selection and explanation | **Operating instructions**                              |

## Buyers don't see your rules

Your operating instructions and acceptance policy are confidential. They steer how the storefront
agent composes and screens, but they're never sent to a buyer or a buyer's agent. What buyers receive
is the proposal in market terms: what is offered, how it fits the brief, and what isn't part of it.

## Pricing guardrails

Every playbook version carries the storefront's pricing guardrails: prices never go below a hard
floor (code enforces this, not the model), and a package discount is at most 15% off the target
price. The 15% cap is fixed today; setting your own cap isn't available yet.

## Operating instructions over REST

All paths are under `https://api.semicola.com/api/v2/storefront`.

| Method and path                                   | What it does                                         |
| ------------------------------------------------- | ---------------------------------------------------- |
| `GET /operating-instructions`                     | Every version.                                       |
| `POST /operating-instructions`                    | Create a version (inactive unless `activate: true`). |
| `GET /operating-instructions/active`              | The version in force (`404` when none is set).       |
| `GET /operating-instructions/{version}`           | One version.                                         |
| `POST /operating-instructions/{version}/activate` | Make a version active.                               |

```bash theme={null}
curl -X POST "https://api.semicola.com/api/v2/storefront/operating-instructions" \
  -H "Authorization: Bearer $SEMICOLA_API_KEY" \
  -H "X-Account-Id: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Lead with premium CTV for brand campaigns. Pair CTV with streaming audio for reach.",
    "notes": "Holiday season update",
    "activate": true
  }'
```

`content` is required (1–50,000 characters); `notes` (up to 2,000) is a label for the history.
`activate` defaults to `false`: without it the new version waits in history until you activate it, and
with `activate: true` it's created and made active in one step. The create answers `201` with the new
version: `version`, `content`, `notes`, `isActive`, `createdBy`, `activatedAt` and timestamps.

Over MCP, `save_playbook` with `content` creates a version **and activates it** (the page's save does
the same), and `save_playbook` with `activateVersion` makes an earlier version active (the page's
**Make active**).

## Acceptance policy over REST

The same five routes exist under `/acceptance-policy` (`GET /acceptance-policy`,
`POST /acceptance-policy`, `GET /acceptance-policy/active`, `GET /acceptance-policy/{version}`,
`POST /acceptance-policy/{version}/activate`). A create takes `briefAcceptance` (required, up to 50,000
characters), `creativePolicy` (up to 50,000), `notes` and `activate`, which defaults to `false` here
too; it answers `201` with the new version. A version also returns `compiled`, the structured form of
the policy the screener uses. Over MCP, `save_business_rules` saves and activates, like the
**Save and activate rules** button.

## Changes apply to the next brief

A new active version applies to the next brief and the next screen. Proposals already sent keep the
version they were composed under. Every save and activation is recorded in your storefront
[Activity](/guides/audit-logs) as an `OPERATING_INSTRUCTIONS` or `ACCEPTANCE_POLICY` change.

## Not available yet

* A separate selling doctrine (pitch, counter-pitch or pass thresholds) with named starting points.
* Declines written in your own voice from rules you write here; buyers get the standard "no products
  matched" answer.
* Rejecting a new version because it repeats a fact owned by another field.

## Related

* [Playbook](/sell/playbook)
* [AI Business Rules](/sell/ai-business-rules)
* [Merchandising](/concepts/merchandising)