Knowledge-base operations and deployment runbook

Scope

This is a separate PHP application at /Users/dan/Documents/CleanFramework Project/CleanFrameworkKnowledgeBase, using a mirrored Composer dependency on Clean Framework. The original framework backup is documented in BACKUP.md. No Prosperous Pairs access or deployment is permitted through this project without a new express authorization.

Local verification is not permission to publish. No real developer account, provider key, production environment, external database, queue, email, or server has been provisioned. Current implementation uses private single-host files, not a multi-host database. Do not place state on unproven shared/network filesystems.

Build and local checks

Follow-up qualification, 2026-10-17: the installed and pinned candidate Docker copies have a separate Linux Apache/FPM/HTTPS test, with no original dependency adoption or host upgrade. See its explicit fixture contract. The older runtime/import statements below are historical checkpoint context.

This application's installed dependency/runtime are unchanged by the October 20 content reconciliation. New framework reference recipes target locally committed 0.2.0-rc.1 through 84f415b (unpublished, not production-approved) and PHP >=8.5.11 <8.6.0; this KB still has mirrored 0.1.0-rc.1 and the local PHP 8.2.11 profile. Obtain separate dependency/runtime adoption authority before installing anything from the new candidate. Do not run the install example below merely to refresh documentation; php bin/import-docs uses existing vendor.

Run from the application root:

composer install --no-plugins --no-scripts
php bin/import-docs
composer test
node tests/pwa.mjs
php tests/native-http.php
php tests/apache-https.php
php bin/verify

The Apache check is optional elsewhere and reports SKIP unless the documented local Homebrew paths are available. It creates a disposable application copy and standalone localhost Apache configuration; it never edits or reloads an installed site's configuration. It verifies PHP execution, actual .htaccess routing, denial, native HTTPS cookies/CSRF, and logout using an explicitly trusted localhost certificate, not disabled TLS verification.

Native HTTP and quota checks use disposable state and synthetic account records. PHP 8.2.11 and Node are the local verification runtimes; compatibility syntax targets PHP 8.0+, but other actual runtimes remain TO VERIFY. GD is needed only to regenerate PNG icons with php bin/build-icons. cURL is required for the optional live adapter and HTTP test harnesses.

Hosting prerequisites — authorization required before deployment

• A separately approved hostname/server and deployment owner; never reuse Prosperous Pairs credentials.
• Apache 2.4 with mod_rewrite, mod_headers, mod_mime and authorization support; a supported reviewed PHP handler (mod_php or FPM), Composer dependency installation, and TLS certificates.
• DocumentRoot set to the application's absolute public/ directory. Allow required .htaccess overrides or deliberately reproduce its rules in reviewed host configuration. A wrong document root is not cured by hidden-file rules.
• Confirm app.php executes PHP rather than returning source. Deny every other public PHP file, hidden files, backup extensions, directory listing, and private-directory traversal.
• Set APP_ENV=STAGE or PROD explicitly and independently. Secure-cookie configuration may not be disabled in hosted environments. Verify HTTPS forwarding only from exact approved trusted proxy networks; do not trust arbitrary X-Forwarded-* headers.
• Give the service user read access to code and private approved content, and write access only to its private environment runtime. Keep code/content read-only to the web worker where practical. Atomic state locks currently enforce private directory modes; the service user must own writable state.
• Provision accounts via the operator CLI only after host approval. Passwords use a secure pipe, are native-hashed, and do not appear in command arguments. There is no public registration/default credential.
• Leave AI disabled until the independent AI_RUNBOOK.md checklist is approved and tested. Documentation-only deployment needs no provider credential.

Do not expose phpinfo, a public console, test routers, backups, development snapshots, or arbitrary file browsers. Keep tests and operator commands outside DocumentRoot.

Account/session operation

bin/developer add|revoke|allow-ai|deny-ai username uses the selected environment's private account store. DEV, TEST, STAGE and PROD accounts/sessions/quotas never implicitly share state. Account records use a stable lock and atomic same-directory replacement; malformed/corrupt state fails closed.

Sessions use HttpOnly, SameSite=Strict, hosted Secure cookies, 30-minute idle timeout and 8-hour absolute timeout. Login rotates the session ID and CSRF proof; logout is a CSRF-protected POST. Current account enabled state, credential version, and AI permission are refreshed on protected requests. Browser foreground/session restoration revalidates access; downloaded/copied content is not retractable.

The application's local access journal stores only known events, timestamps and hashed subjects, with a 10,000-event daily/2 MiB bound. Audit failure prevents a new login grant; logout still clears authenticated state. Infrastructure logs are a separate policy: do not log request bodies, query strings, cookies, Authorization, or full provider responses. Configure path-only access logs (method, path without query, status and time) and approved retention before hosting.

MFA/enterprise SSO, account recovery/password-reset workflows and fine-grained team ACL administration are not shipped by this build. Decide whether they are required before exposing a deployment; do not describe password-only access as sufficient for every threat model.

Documentation publication

config/documents.php is the fixed editorial allowlist. Framework guides come from the independent local dependency checkout; authored how-tos and application policies come from this app; eight complete Reading List examples are imported as inert code-fenced article text. Historical logs, credentials, arbitrary files and unapproved source remain excluded.

config/documentation-context.php carries the reviewed candidate/checkpoint, archive hash and version-boundary notes. Each new article body records its original source hash separately from its publication hash. Reconcile that metadata when importing a later handoff. Old revision bytes remain immutable. The new source candidate and this application's installed vendor are separate version surfaces, not an implicit dependency upgrade.

php bin/import-docs builds immutable hash-named revisions and atomically updates the current pointer only after all files match. A request pins one revision. The repository validates manifest/document digests and permissions; source links resolve to protected article IDs, never an arbitrary filesystem route. Import is a human operator command, not an AI publishing capability.

An interrupted importer can leave an unpublished partial revision, but the previous published pointer remains active. Re-running identical approved sources completes/verifies the revision. Do not manually overwrite hash-named files.

The first build's flat snapshot remains as a compatibility artifact; current.json selects revisioned content. Retain prior revisions long enough for in-flight requests. Old revision removal is an explicitly reviewed offline operator operation after backup; no web cleanup endpoint exists.

Runtime retention, capacity and backups

Before hosting, assign an operator schedule for session/rate-file/access-journal cleanup, disk alerts, and backup verification. The application rate limiter is file-backed; attempted distinct usernames/IPs can create many limiter files over time. File caps/monitoring and operator cleanup are operational requirements, not an unlimited-storage guarantee. Search returns 12 results and bounded excerpts; run load tests for the intended team size.

Use php bin/retention plan for an inventory of eligible runtime files. The shipped operator tool only plans; deletion requires reviewed offline filesystem work, a verified backup, and a deployment-owned retention/legal-hold decision. AI-ledger pruning keeps roughly the last 30 UTC days on the next reservation; access journals/sessions/rate files and backups have separate schedules. Pseudonymous hashes remain sensitive operational metadata.

Back up code/lockfile, approved content/current pointer, and selected environment state (accounts, sessions if required, quota/audit files) with restrictive encrypted storage. Do not put a populated .env in a public release archive. Quiesce operator imports, account updates and requests while snapshotting file-based state, or use a proven filesystem snapshot; copying live files sequentially is not a consistent multi-file backup.

Restore to a fresh isolated directory. Verify archive integrity, hashes, private permissions and accounts without activating AI/network integrations. Test login/revocation and quota continuity before replacing the deployment. Restoring an old spending ledger can reset consumed quotas: reconcile provider spending and current ledgers before enabling AI. A restoration never authorizes replays of pending requests.

PWA release rules

The manifest installs an always-dark, online-only workspace. Cache allowlist: non-sensitive CSS/JavaScript, generic icons, install manifest and identity-free offline HTML. No private navigation response, API/auth/search result, question, answer or account is cached by the worker. No browser localStorage/sessionStorage/IndexedDB conversation store or background sync is used.

Increment the service worker's shell cache version whenever cached UI assets change. Updates activate normally after old tabs close; no forced skipWaiting interrupts private form state. Old worker versions delete only owned cache names, not unrelated applications. Verify no query/authenticated/redirected/private response enters the shell cache.

Test physical iOS Safari Add to Home Screen and Android/Chromium installation, update, logout/account switch and offline fallback before rollout. Local responsive emulation and service-worker contract tests are not physical-device certification. Reconnect requires a current valid session; the offline page contains no article or identity.

Readiness and safe rollback

See REMAINING_WORK.md for actual evidence and outstanding external acceptance. Inspect real files and rerun checks after interruptions; BUILD_LOG.md records completed checkpoints, not a substitute for verification.

Rollback by selecting a previously verified application/content revision while preserving current accounts, audit, sessions and spending-ledger continuity. Disable AI first if correctness/transport/price policy is in doubt. Never modify the original Clean Framework or Prosperous Pairs as a knowledge-base rollback action.

Editorial provenance

Source: docs/DEPLOYMENT_RUNBOOK.md. Source SHA-256: 7fecb00e2748f531d772a3432db4dbae895aa608c7c12e15a77a4cbe3b81139c.

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