PAINKILLER / Electrome Documentation

Last updated: 2026-05-18 AST (Alaska) Created: 2026-04-22 AST (Alaska) — restored from .migration-backup/docs/ on 2026-05-18 after post-monorepo-migration cleanup

Single source of truth for product, architecture, API, SDK, operations, and policy documentation across the painkiller.care ecosystem (consumer / My Care portal, patient portal, provider portal, retailer portal, affiliate portal, investor portal, admin portal, admin IR sub-portal).

Agent memory: [replit.md](../replit.md) lives at the repo root and is loaded into the agent context on every session. Do not move it. [replit1.md](../replit1.md) holds long-form locked notes.

Status index: see [00-DOC-STATUS-latest-v1.16-2026-04-26.md](./00-DOC-STATUS-latest-v1.16-2026-04-26.md) for what is complete vs draft vs missing across the Erik-authored doc set, and [08-status/2026-05-platform-update-latest-v1.0-2026-05-18.md](./08-status/2026-05-platform-update-latest-v1.0-2026-05-18.md) for the May 2026 monorepo-migration & post-migration work summary.

Production exclusion: nothing in docs/ is bundled, imported, or served. The Vite build (artifacts/painkiller) and esbuild bundle (artifacts/api-server) pull only from their respective src/ trees. Repository-only.

Time zone: all dates and timestamps in this folder are Alaska time (AST). The agent always pulls timestamps from the system clock, never from a user-stated time.

---

Folder structure at a glance

docs/
├── README.md                                       <-- this file
├── 00-DOC-STATUS-latest-v1.16-2026-04-26.md        <-- status index of the Erik-authored doc set
│
├── 01-product/         Product vision, portals, roles, catalog, referral, exec summary
├── 02-architecture/    System design, signing, sync, KB, agent memory, integrations
│   ├── backend/        Backend system overview
│   ├── frontend/       Mobile UX + nav performance hardening playbooks
│   └── middleware/     Middleware overview
├── 03-api/             HTTP API contract: OpenAPI, Swagger, auth, errors, surface map
├── 03-flows/           Cross-portal flows (e.g. consumer-to-patient upgrade)
├── 04-sdk/             NPM SDK strategy, package matrix, adoption, migration, releases
├── 05-operations/      Deployment, runbooks, performance, observability, commission, Stripe
│   └── deployment/     Cloud migration, quickstart, portability cheatsheet
├── 06-policies/        Behavior, role gates, checkout, AI policies
│   ├── security/       Secrets, access control, PHI/PII/HIPAA, Growthie security behavior
│   └── content/        Terminology, SEC/FDA compliance, on-behalf-of letters
├── 07-reference/       Design system, frozen specs, as-built companions, mobile porting
│   ├── design/         Design guidelines, GUI history, portal design inventory
│   ├── mobile/         React Native porting guide
│   └── specs/          Frozen original specs + as-built companions
├── 08-status/          Time-bound platform updates (frozen snapshots)
├── 99-archive/         Frozen historical artifacts (communications, prompts, research)
├── drafts/             Draft inbox + governance
│
├── GigaPower Kit/      Erik's Replit Agent enhancement kit v1.5.0 (memory, plan-then-build,
│                       multi-agent coordination, gigapower_runtime middleware)
├── Electrome-BIEL/     BIEL / RecoveryRx purchase-order references
├── _Growthie-Painkiller-messages/   Inter-agent message logs (Growthie ↔ Painkiller)
├── mobile/             Mobile-specific runbooks (separate from 02-architecture/frontend)
├── plans/              Active multi-week plans and milestones
├── specs/              Misc. specs not yet promoted into 07-reference/specs/
├── messages/           Operational message templates
├── poc-templates-npm/  Connect-cluster-mini POC templates
├── assets/             Shared images for the doc set
├── TEMP/               Scratch — do not link to from anywhere
│
└── ── post-migration HealthCloud OS Solution docs ──
    │   These were authored AFTER the pnpm-monorepo migration (May 2026) to document
    │   the demo-mode HealthCloud OS Solution layer (mock clients, JSON fixtures).
    │   They live alongside Erik's numbered taxonomy, not inside it.
    │
    ├── overview/, architecture/, solution/         Solution-layer overviews
    ├── api/, api/healthcloud-os/, api/growth-os/   Future API surface (demo-mode today)
    ├── agents/, ams/                               20-agent registry walkthrough
    ├── connectors/                                 24 external-system connector index
    ├── workflows/, events/                         Workflow state machines + event taxonomy
    ├── fhir/, knowledge-graph/                     Clinical + KG schema docs
    ├── governance/, security/, permissions/        Solution-layer policy docs
    ├── mock-data/, sdk/, testing/, demo-scenarios/ Build/test/demo guides
    ├── publisher/, operations/, ux/, schemas/      Listing, runbooks, design tokens, JSON schemas
    ├── ai-visibility/                              AI/LLM crawler surface (llms.txt, sitemaps,
    │                                                structured data, JAMIA paper draft)
    ├── intelligence-core/, evidenceos/             Planning + content-integrity rules
    ├── integrations/                               Cross-agent integration briefs
    ├── ops/                                        Recent runbooks (publishing, social-preview)
    └── lint-skipped-warnings.md                    Registry of 77 intentional ESLint skips
                                                    (May 2026 sweep)

Top-level JSON registries (machine-readable, sit next to this README): AMS_REGISTRY.json, CONNECTOR_REGISTRY.json, ENDPOINT_CATALOG.json, EVENT_TAXONOMY.json, GROWTH_OS_ENDPOINTS.json, KG_SCHEMA.json, PERMISSION_MATRIX.json, SOLUTION_MANIFEST.json, WORKFLOW_STATE_MACHINES.json.

---

Filename convention

Every doc filename ends with the date of its most recent meaningful change (creation date for a brand-new doc; last-update date thereafter).

Six hard rules

1. One file per topic. When you update a doc, rename it in place (same base name, bump version, change the date). Never accumulate -v1.0, -v1.1, -v1.2 siblings; git history preserves prior versions.
2. Date in filename = most recent meaningful change. Every *.md MUST also carry a > Last updated: YYYY-MM-DD HH:MM AST (Alaska) line immediately under its H1; bump this line on every edit. New docs additionally carry a > Created on: YYYY-MM-DD HH:MM AST (Alaska) line directly above it.
3. Pre-existing files (created before 2026-04-19) without a date suffix are renamed lazily on next update; valid until then. Post-migration files (authored after 2026-05-14) follow the same rule.
4. Originals are never edited to "match reality." When a frozen original spec/design diverges from the deployed system, ship a sibling -as-built-.md next to the original.
5. Production exclusion: nothing in docs/ is bundled, imported, or served. Repository-only.
6. Every doc carries its own brief change log. Inside each *.md, include a short ## Change log table near the bottom with one row per version: | Version | Date (AST) | Change |. The on-disk file only ever holds the LATEST version, but its embedded change log preserves the human-readable version history.

Update vs Create

• Update an existing doc when the behavior it describes changed, when a cross-referenced doc materially changed, or for a typo / clarification. Method: rename the file to same-base-vNEXT-YYYY-MM-DD.md, edit content, append a row to its own change log, then update 00-DOC-STATUS.
• Create a new doc when a topic has no existing home. Start as name-draft-YYYY-MM-DD.md, then promote to name-latest-v1.0-YYYY-MM-DD.md once: all sections have real content, owner has reviewed, linked from this README + at least one other doc, and a peer (Erik / Ken / Bojan / architect agent) has read it end-to-end.

---

Post-migration restoration note (2026-05-18)

This README and the full numbered taxonomy (01-product/ through 99-archive/) plus the GigaPower Kit, Electrome-BIEL, _Growthie-Painkiller-messages/, drafts/, plans/, specs/, mobile/, and poc-templates-npm/ folders were restored from .migration-backup/docs/ on 2026-05-18.

During the pnpm-monorepo migration (May 2026, when server/ + client/ were split into artifacts/api-server/ + artifacts/painkiller/), this rich doc tree was stripped down to a minimal subset focused on the new HealthCloud OS Solution layer. The restoration brings the full Erik-authored taxonomy back alongside the post-migration additions (none were lost).

Known content drift to address in subsequent passes:

1. Path references — many restored docs reference server/, client/, and shared/ paths from the pre-monorepo layout. The equivalents are now artifacts/api-server/src/, artifacts/painkiller/src/, and artifacts/painkiller/src/shared/. These references are still informative (the file basenames are unchanged) but should be rewritten on each file's next substantive update.
2. 00-DOC-STATUS-latest-v1.16-2026-04-26.md — last refreshed before the monorepo migration. Treat as accurate for content authored before 2026-04-26; cross-check with 08-status/2026-05-platform-update-*.md for everything since.
3. Excluded from restoration: old_electrome_com_website_assets/ (196 files of WordPress export — available in .migration-backup/docs/old_electrome_com_website_assets/ if needed), all paired .pdf companions (regeneratable per Rule 2; will be regenerated after MDs are current), .docx binaries, 0-byte placeholders, and one (copy).md duplicate.

See [08-status/2026-05-platform-update-latest-v1.0-2026-05-18.md](./08-status/2026-05-platform-update-latest-v1.0-2026-05-18.md) for the May 2026 change summary (monorepo migration, ESLint sweep 826→77 warnings, chunk-error self-healing fix, security PRs #403-#409, doc restoration).

---

Doc-update triggers

1. Explicit user instruction.
2. Code change in a path paired to a doc.
3. Architectural change — replit.md and replit1.md are updated in addition to any doc-set changes.
4. End-of-task code review flags doc drift.
5. Quarterly doc-drift sweep (planned).

See [00-DOC-STATUS-latest-v1.16-2026-04-26.md](./00-DOC-STATUS-latest-v1.16-2026-04-26.md) for the canonical "what's complete vs draft vs missing" view for the Erik-authored taxonomy, and the per-folder README.md for the post-migration HealthCloud OS Solution docs.

---

Originals vs as-built (policy)

The docs/ taxonomy distinguishes between three classes of artifact:

1. Specs / design / original positioning documents (e.g. 07-reference/specs/investor-portal-spec.pdf, the original ai-native-ecosystem exec summary). These are frozen. We do not retroactively edit them when the system evolves.
2. Living docs (everything in 01-product/, 02-architecture/, 03-api/, 03-flows/, 04-sdk/, 05-operations/, 06-policies/, 07-reference/design/, 07-reference/mobile/ that is -latest-, plus the post-migration solution docs). These reflect the system as deployed today and are version-bumped + date-bumped on every substantive change.
3. As-built companions (*-as-built-vX.Y-YYYY-MM-DD.md). When a frozen original (class 1) materially diverges from reality (class 2), an as-built companion is added in the same folder as the original, clearly labeled, cross-referenced from this README and from 00-DOC-STATUS, and dated. The frozen original is left untouched.

Change log