gemstone-nexus · Phase 6

DOC06 — Master Prompt

← Documents

Metadata

iddoc_idtitlecategorysource_pathsummarycontent_hashindexed_at
24DOC06DOC06 — Master Promptdoc_suiteDevResources/docs/DOC06-Master-Prompt.mdThis is the last document in the GemStone set, built only after DOC01 through DOC05 and DOC07 through DOC21 (plus Amendments 1 and 2) are complete, because it aggregates and references them rather than standing alone. Cursor should treat this document as the entry point for any GemStone build task, and should follow its section references back to the source document for full detail rather than relying on this summary alone for anything schema-, endpoint-, or test-critical.152ad05ad821bf759d078ee044407bde4ab75db82026-07-22 18:33:18

Content

# DOC06 — Master Prompt

*Aggregated Cursor build instructions, referencing the complete GemStone document set*

**Initiative:** GemStone · **Version:** v2.0 (Rewrite) · **Status:** Approved for Build · **Date:** July 17, 2026

## 0. How to Use This Document

This is the last document in the GemStone set, built only after DOC01 through DOC05 and DOC07 through DOC21 (plus Amendments 1 and 2) are complete, because it aggregates and references them rather than standing alone. Cursor should treat this document as the entry point for any GemStone build task, and should follow its section references back to the source document for full detail rather than relying on this summary alone for anything schema-, endpoint-, or test-critical.

## 1. Non-Negotiable Technology Constraints

- AI/ML stack is exclusively Western-origin (PyTorch, Hugging Face, vLLM, Ollama, Whisper, MLflow, OR-Tools). PaddlePaddle, MindSpore, MegEngine, OneFlow, and all Chinese-origin frameworks are prohibited, no exceptions. See DOC17 Section 1.
- Messaging is AWS-native only (SES, AWS End User Messaging, SNS for push/pub-sub only, FCM). Twilio and other third-party messaging vendors are prohibited.
- MQTT broker is always Eclipse Mosquitto. EMQX is prohibited.
- Mobile frontend is Capacitor. Do not scaffold React Native or Expo for GemStone mobile work; see Amendment 2 for what this superseded.
- Capacitor is first-class and subject to atomic concurrency: every frontend change ships web + Android + iOS in the same change set; a Capacitor build or test failure is a feature failure and blocks the phase gate.
- UI is strict DataRightTailwind (`DataRightAppBundle/DataRightTailwind/` and `DATARIGHT_TAILWIND.md`). Login is modeled on HorizonORBIT (HorizonCRM repo; clone at frontend stage). Auth0 Universal Login with Google, Facebook, and LinkedIn social connections maps to SuperAdmin, Org Admin, Practitioner, and GemStone Agent.
- Inference is sovereign-first: Ollama + Whisper + Piper on the T4; Gemini is development mode only. Switch mode via `PUT /api/v1/gemstone/ops/inference-mode` (see contract-notes.md).
- Data tier: PostgreSQL (app schema) + Redis session state with AOF + SQLite Project Ledger. GemStone is an MCP client to the remote Atlas Vault (MCP Index B); do not embed a local Atlas Vault.
- Primary build/run target is T4 GoldenAMI EC2 `i-04333dae160ab0daa`. Local secondary is a clean clone of `DataRightGoldenOVAFullBase` only. Do not target the retired GemStone VM at `10.0.0.210`.
- Build in this repo (`GemStone-Nexus-StackOne`). `DataRightAppBundle` is bootstrap machinery. After the first green GoldenAMI build, purge legacy product naming from the prior StackOne extraction (CI grep gate required).
- Every Didymus task, regardless of source, requires human approval before execution. Never scaffold an autonomous-execution code path for any feature category, at any maturity level. See DOC03 Section 6 for the schema-level enforcement pattern. Practitioner credential provisioning: DIDYMUS-PLAYBOOK.

## 2. Repository and Container Structure

```
gemstone/
  gemstone-api/          # FastAPI backend: sessions, tiers, domain packs, Didymus client
  gemstone-mobile/       # Capacitor app: Field Mode, Extended Sessions, Notebooks/Recents UI
  gemstone-tts/          # Piper TTS streaming service
  atlas-ollama/          # Whisper large-v3 STT via Ollama
  gemstone-db/           # PostgreSQL schema and Alembic migrations
  gemstone-redis/        # Redis session state, AOF persistence enabled
  mcp-server/            # MCP Index B client for Atlas Vault integration
  ledger-api/            # GemStone Project Ledger (DOC19)
  tests/
    unit/                # Pytest (backend), Vitest (frontend)
    integration/         # Pytest + test DB
    e2e/                 # Playwright
    uat/                 # Structured scripts per DOC20
  Makefile
  docker-compose.yml
  .env.example
```

## 3. Required Environment Variables

| Variable | Purpose | Source of Truth |
| --- | --- | --- |
| GEMSTONE_DB_URL | PostgreSQL connection string | DOC03 Section 1 |
| GEMSTONE_REDIS_URL | Redis connection string, AOF enabled | DOC02 Section 6.3 |
| ATLAS_MCP_ENDPOINT | MCP Index B endpoint for Atlas Vault | DOC02 Section 6.4 |
| DIDYMUS_HUB_URL | Didymus Hub endpoint (external dependency) | DIDYMUS-ARCH-01 |
| VOICE_TIER_CLOUD_ALLOWED | Boolean gate on cloud STT/TTS providers by tier | DOC03 Section 2 |
| RESEARCH_AGENT_PROVIDERS | Comma list of approved providers (brave, perplexity, claude, gemini) | DOC03 Section 8 |
| WAKE_PHRASES | JSON array, configurable, multiple simultaneous phrases | FR-GS-008, DOC05 |
| GATE2_SUPERVISED_CYCLE_N | Configurable count, set from admin/dev session, not hardcoded | FR-GS-008, DOC26 Section 5 |

## 4. Makefile Targets Cursor Must Implement

```
make up          # docker compose up, all services
make down        # docker compose down
make migrate     # Alembic upgrade head against gemstone-db
make test        # runs unit, integration, e2e, uat in sequence; fails fast on any tier
make lint        # ruff (Python), eslint (TypeScript)
make rollback    # restore prior known-good deployment; see DOC02 Section 6.1 exit criteria
make sbom        # regenerate Syft SBOM, cross-check against DOC17
```

## 5. Security Tier Enforcement Rules

- TierGuard (DOC03 Section 9) is the single enforcement point for tier-gated behavior. Do not implement tier checks in more than one place; a second enforcement point is itself a defect per DOC16 Section 2.
- Tier is immutable after session creation, enforced at the database constraint level, not only in application code. See DOC03 Section 1 for the schema and DOC14 Section 3 for the required test.
- Session transcripts must never be transmitted externally in any tier. This is an absolute; do not build an exception path even for debugging.

## 6. Orchestration Rules

When implementing task-dispatch or approval-queue logic, GemStone is always the single presentation surface. Do not build a separate approval UI for tasks originating from Cursor, Claude, or Gemini; route all suggestions through the same GemStone-facing queue regardless of source, per DOC03 Section 12 and the Didymus task state machine in DOC03 Section 6. Every task record requires approved_by and approved_at fields that structurally block the transition into RUNNING; see DOC14 Section 3 for the required test and DOC08 Section 3 for the incident runbook if this is ever violated.

## 7. Mobility Layer Build Rules

Field Mode audio uses standard Capacitor WebView APIs (getUserMedia/MediaRecorder), identical to the current web app implementation; no native plugin is required for this mode. Extended Session audio requires native background-audio entitlements: iOS AVAudioSession with UIBackgroundModes: audio declared in native configuration, and Android a foreground service declared with FOREGROUND_SERVICE_TYPE_MICROPHONE carrying a persistent notification. Do not conflate these two audio paths into a single implementation; see DOC02 Sections 6.5-6.6 for phase-separated gate criteria and GS-MOB-01 Section 10 for the full architecture.

Raw audio is captured in full the moment the mic opens, no ambiguous pre-buffer state, and is discarded immediately once transcribed, indexed, and vectorized into Atlas Vault. On failure, hold audio in chunks and flag both in-app and at the system log level; see DOC08 Section 4 for the runbook and DOC21 for the required dashboard view.

## 8. Testing Requirements Before Any Merge

Every merge must pass the coverage thresholds in DOC14 Section 4 and include, at minimum, the representative test patterns in DOC14 Section 3 for any touched subsystem. A feature is not complete when it works; it is complete when its corresponding DOC02 phase gate criteria and DOC20 UAT script (if applicable) both pass.

## 9. Document Cross-Reference Index

| Document | What Cursor Should Consult It For |
| --- | --- |
| DOC01 Abstract | High-level orientation to what GemStone is and why |
| DOC02 SOW | Phase boundaries, entry/exit gate criteria, RACI, risk register |
| DOC03 PRD | Schemas, API contracts, state machines, RBAC matrix, tier logic |
| DOC04 User Stories | Given/When/Then acceptance criteria per capability |
| DOC05 Feature Requests | What is committed vs. deferred vs. unscoped, with dependencies |
| DOC07 Punchlist | Per-phase checklist with owner and verification artifact |
| DOC08 Playbook | Operational runbooks for defect scenarios |
| DOC09 Glossary | Canonical term definitions |
| DOC10 Training and Support | Onboarding scripts, support escalation tiers |
| DOC11 Promotion and GTM | Public messaging guardrails |
| DOC12 Development History | Why prior architectural decisions were made |
| DOC13 Diagrams | Sequence and state diagrams for voice, approval, tier cascade, resume |
| DOC14 Unit Test Results | Coverage targets and representative test code |
| DOC15 DR/BC | RTO/RPO targets, backup schedule, failover requirements |
| DOC16 Security and Pen Testing | Threat model, standing absolute rules, test scope |
| DOC17 BABA Compliance | Origin compliance checklist |
| DOC18 SBOM | Approved dependency and license baseline |
| DOC19 Project Ledger | Ledger schema, Atlas distillation feed |
| DOC20 UAT Framework | Structured acceptance scripts, step by step |
| DOC21 Platform Dashboard | Required metrics and their calculation |
| Amendment 1 | Didymus integration reconciliation against the original suite |
| Amendment 2 | Mobility Layer reconciliation against the original suite |
| DOC26 Bootstrap/Self-Hosting | Bootstrap and Self-Hosting phase-gate criteria (`DOC26-Bootstrap-Self-Hosting.md`) |
| DIDYMUS-ARCH-01 | Didymus hub architecture, worker contract, task storage, MCP tools |
| DIDYMUS-PLAYBOOK | Practitioner provisioning of AI workers and approval-queue ops |
| GS-MOB-01 | Field Mode, Extended Sessions, native audio bridge, wake-word |

## 10. Formatting Standards

- No em dashes in any generated content or documentation.
- No horizontal rules in Word documents; use spacing and bold headings.
- Segoe UI Semibold for primary headings, Segoe UI for subheadings, Segoe UI Light for body text.


---
NEXTECH Business Technology Management LLC · nex-tech.biz · (941) 499-5505