Knowledge-base AI policy and activation

Current boundary

The application supplies a read-only OpenAI Responses adapter and deterministic fake-provider checks. AI is OFF by default; there is no key or default model. No live call has been made. The core framework's generic AI mechanics and this application's adapter are distinct components.

No tools, shell, database mutation, file writes, URL fetching, deployment, automatic drafts, publishing, or provider conversation chaining are exposed. Approved excerpts and the submitted question are the only untrusted provider input. The trusted prompt/schema version is knowledge.answer.v1.

Activation prerequisites

An authorized operator must approve all of the following for one independent environment:

• A dedicated provider project, restricted server-only key, organization/project spending controls, billing owner, and credential rotation/revocation process.
• A supported Responses/strict-structured-output model selected from current official documentation. The app intentionally does not guess a model or price.
• Permission to send proprietary documentation excerpts and questions to OpenAI; review the provider retention policy and the application's business/legal obligations. Do not submit credentials, customer data, production logs, or unnecessary personal data.
• Conservative input/output price ceilings, daily user/global request limits, and daily budget ceilings.
• Fake-provider checks, then separately authorized live sandbox refusal/usage/model-compatibility/adversarial evaluation. A matching JSON schema does not establish factual correctness.

Environment settings

Use the selected prefix, such as DEV_, STAGE_, or PROD_, independently for these names. Prefer service-level environment/secret injection. Never commit a populated .env or put a key in a command argument, page, log, frontend bundle, or browser storage.

Unit example only, not a quoted provider price: $10 per million tokens is 10,000,000 micro-USD per million. One micro-USD is $0.000001. Supply ceilings at least as high as applicable current uncached/token/reasoning charges; re-review whenever selecting a model or when prices change.

The app reserves ceil((50,000 × input ceiling + output-token ceiling × output ceiling) / 1,000,000) micro-USD before each call. It retains that full reservation for success, refusal, invalid schema, timeout, and unknown outcome. This is deliberately conservative, not an exact invoice/refund ledger. Application limits cannot guarantee provider billing if prices are configured incorrectly; provider-side budgets and monitoring remain mandatory.

Request envelopes are bounded to 45,000 encoded bytes plus conservative framing headroom, context to four excerpts/22,000 encoded bytes, output to 16,000 validated JSON bytes, transport to 5-second connect/30-second total and 128 KiB response. Reported input usage beyond 50,000 tokens or output above the configured ceiling is rejected without refund. No automatic retry is performed.

Developer permission and consent

Documentation access is docs.read; it does not imply ai.ask. Enroll a developer first, then separately grant/revoke AI in the selected environment:

APP_ENV=DEV php bin/developer allow-ai your.username
APP_ENV=DEV php bin/developer deny-ai your.username

These are operator actions, not instructions to run against a deployed host without authorization. Current account and credential version are checked before and after a provider call. Each question also requires the developer's explicit sharing checkbox. General suggestions require a separate opt-in and are displayed as unverified, not framework facts.

Grounding and privacy limits

Retrieval filters permissions before reading document bodies. The model receives only selected approved visible excerpts and their IDs/hashes, with no session, password hash, username, arbitrary paths, or historical conversation.

Output passes the reusable framework's closed schema validator. Citations must identify a selected excerpt, match its hash, quote text actually present in that excerpt, and still match the currently published authorized article. Unknown/forbidden citations and revision/account changes suppress the answer. Grounded answers require citations; insufficient/refused responses cannot pretend to have grounding.

These checks establish citation provenance, not semantic entailment for every generated statement. A malicious question/excerpt can still influence model prose; prompt separation and no-tool design limit impact, while sandbox evaluations and human review address residual hallucination/injection risk. Browser output is text-only. Do not execute generated code without normal review/testing.

Questions/answers are not persisted server-side or in browser local/session storage. Only the active page holds the latest transient answer. Private responses are no-store and PWA-excluded. Logout/revocation stops subsequent requests; already viewed/copied/screenshot content cannot be recalled from a device.

The private environment ledger retains bounded request IDs, hashed subjects, timestamps, prompt version, reservation and classified status for up to 30 days of active reservations. It never logs questions, answers, excerpts, keys, or raw provider bodies. Interrupted calls remain pending/charged and require operator reconciliation; they are not replayed. Hashes are pseudonymous metadata, not guaranteed anonymity. Backups have independent approved retention.

Provider retention — reviewed 2026-10-10

store:false disables Responses application-state storage; it does not promise zero provider retention. OpenAI documents default abuse-monitoring retention of up to 30 days, with stated exceptions, and eligibility/approval requirements for modified monitoring or Zero Data Retention. API data is not used for model training by default unless opted in. Recheck policy before live activation.

Sources: OpenAI data controls, structured outputs, Responses migration.

Verification and rollback

Run composer test and node tests/pwa.mjs before any authorized live evaluation. Use only disposable provider projects and synthetic questions for that evaluation. Never use Prosperous Pairs credentials.

Rollback: set the selected environment's KB_AI_ENABLED=false, remove the provider key from service injection, restart/reload workers, and revoke the dedicated key through its owner if compromise is suspected. Do not erase ledgers to reset spending controls or conceal history.

Editorial provenance

Source: docs/AI_RUNBOOK.md. Source SHA-256: f111deb40f3ba1603879644ef105f1bb0a0ded166d2972d62f9d9456757fa3e3.

Knowledge-base application source; editorial checkpoint 2026-10-20. See candidate status and adoption boundary.