Below is the final, refined, single-source specification, with AI modes fully clarified and ambiguity removed, while preserving your existing code and intent.
No implementation detail is added. No working code is invalidated. This is a conceptual lock, not a refactor request.
You can treat this as the authoritative spec going forward.
⸻
DOCUMENT INSTRUMENT
Control without chaos
⸻
- What this is
Document Instrument is a document-centric workflow engine for professionals who touch revenue.
A single living document acts as the control plane for real work: • planning • pricing • offers • orders • campaigns • exports • publishing
The document is not a file. It is an orchestrator.
⸻
- Core principle (locked)
One document = one source of truth • UI is minimal • State lives on the server • Mutations happen only via server actions • Suspense coordinates partial re-rendering • No client-side orchestration • No silent side effects
Everything important is: • explicit • traceable • reversible
⸻
- What this is NOT
Document Instrument is not: • a dashboard app • a generic CRM • a Zapier-like automation system • a no-code workflow builder • an AI toy or “chat product”
If it drifts toward any of these, it is out of scope.
⸻
- Target users (v1) • Independent professionals • Consultants and operators • Trip designers & experience sellers • Small teams managing pricing, offers, and campaigns manually today
This is for people who touch revenue, not casual note-takers.
⸻
- Core workflow (authoritative)
5.1 Start with a document • User logs in • Lands on a blank document canvas • No menus by default • Minimal navigation between documents
5.2 Compose deterministic sections
A document is composed of typed sections: • text blocks • planners (rows × columns) • line items (prices, quantities, totals) • trip builders • metadata blocks • skill projections (cards rendered from skills)
Each section: • has a schema • is renderable and editable • autosaves • may trigger explicit server actions
⸻
- Trigger real operations
From inside the document, the user may explicitly trigger: • generate a trip • calculate pricing • insert or overwrite line items • promote Places → Contacts • generate offers • send emails • export data • publish to magazine
Rules (non-negotiable): • All triggers go through server actions • Prisma access only in actions/ • Explicit user confirmation required • revalidatePath / revalidateTag required • Suspense handles refresh
No polling. No background magic.
⸻
- Status-driven lifecycle
Entities evolve by status, not deletion: • Draft → Proposed → Confirmed • Orders and logs are permanent • Everything else is revisable or disposable • Revisions create new versions
This keeps the system auditable and honest.
⸻
- Editor & Sidebar (locked) • Editor = control plane • Sidebar = instrument panel
Rules: • Nothing complex lives in the canvas • All tools live in the sidebar • Nothing runs without explicit user intent
⸻
- Skills, Cards, Posters (resolved)
9.1 Canonical knowledge system
The system already contains a mature card engine: • Chapter • PromptCard • Palette • Highlight
This is the knowledge layer.
Locked rule: Skills project into cards. Cards are never duplicated.
9.2 Skill layer (definition) • MicroSkill → capability / offering • MicroSession → delivery format • SessionStep → operational step • PromptCard → knowledge atom
SessionSteps reference or project into PromptCards.
No parallel “StudyCard” domain is allowed.
9.3 Rendering rule • Documents render skills as cards • Posters, postcards, PDFs are render-only projections • No content duplication • No mutation during rendering
Canonical rule:
Artifacts persist. Authority resets.
⸻
- Publishing (Magazine) • One magazine per scope • Publish: • entire document, or • individual sections
Publishing: • generates unlisted, shareable URLs • is exportable as PDF
Magazine is a projection, not a fork. The document remains the source of truth.
⸻
- Architecture (locked)
app/(pages)/ page.tsx → Server page (read-only orchestration) layout.tsx → Layout (client or server) components/ → Client UI (no data access) actions/ → Server authority (ONLY Prisma access) lib/ → Pure helpers context/ → Client-only UI state types/ → Domain truth api/route.ts → Integration surfaces only
Rules: • Prisma access ONLY in <entity>/actions/ • Client components never call API routes • Server pages never mutate • Server actions orchestrate mutations + revalidation • API routes are not app plumbing
⸻
- AI — explicit, bounded, unambiguous (FINAL)
AI is not the product. AI is an assistive instrument.
12.1 Authority split (locked)
There are two layers, with distinct responsibility:
A. Mode Authority (Lifecycle & Intent) • Defines what modes exist • Defines who may select them • Defines which modes orchestrate others • Defines deprecation paths
This layer is system authority, not LLM behavior.
B. Mode Policy (LLM Guardrails) • Defines what the LLM may do • Defines what it can see • Defines how it executes • Defines confirmation requirements
This layer never decides lifecycle or authority.
These layers must never be merged.
⸻
12.2 User-visible AI modes (END STATE)
From the user’s perspective, there are only two modes:
A. General Assistant • Default mode • Document-aware • Continuous across sessions • Used for: • clarification • summarisation • recall • navigation • May read documents • May not mutate entities • May not orchestrate pipelines
This is assistive cognition, not execution.
⸻
B. Coaching Mode (orchestrator) • Explicitly entered • High-context, continuity-aware • Aware of: • current project • session goals • stages & milestones • departments / domains • doctrine rules • cards, postcards, archives • May invoke internal pipelines • All mutations require explicit confirmation
This is guided execution, not chat.
⸻
12.3 Internal execution modes (non-user)
The following modes exist, but are implementation details: • dev • mlv • autopilot • feature / docs / pipelines
They are: • callable only by Coaching Mode • never user-selectable in final state • preserved for reuse and stability • not removed, only hidden
They are capabilities, not experiences.
⸻
12.4 Persona model (locked)
Personas are prompt shapers, not agents.
They: • do not own data • do not run automations • do not bypass schemas
Each persona defines: • allowed domain • tone range • forbidden behaviors • doctrine alignment
Users may: • name personas • slightly tune tone • assign personas to stages
Users may not: • remove constraints • bypass doctrine • create manipulative roles
⸻
12.5 LLM output modes (orthogonal, explicit)
The LLM always operates in one output mode: • reflect → clarify thinking • plan → structure steps • teach → explain principles • review → doctrine check • execute → generate content or code (when unlocked)
These are execution lenses, not system modes.
⸻
- Project intent & restart logic (final)
Option A — Abandon & Start Fresh
Hard reset. Clean slate.
Option B — Restart With Insight (locked) • New project created • All statuses reset • Previous project becomes read-only reference • Artifacts carry over as drafts, not progress • Code is marked “requires review”
Canonical rule:
Artifacts persist. Authority resets.
Option C — Professional / Agent Mode
Multiple active projects allowed.
Option D — Idea Workshop (Draft Only) • Free exploration • No milestones • No program activation • May later be promoted to a project (reset applies)
⸻
- Definition of Done (MLV)
MLV is reached when: • a document can be created and composed • autosave works • one sidebar tool works end-to-end • trip builder produces pricing rows • Places → Contact promotion works • a manual email sequence is logged • one export works • one magazine page is published
Stop. Ship. Pilot.
⸻
- Strategic positioning (external)
Sell this as:
A professional document instrument
Not: • AI software • automation platform • productivity app
Lead with: • control • safety • explicit actions • no dashboards • no automation chaos
AI assists. The document leads.
⸻
- Status • Specification: LOCKED • Architecture: PROVEN • Remaining work: execution only
⸻
Canonical anchor (keep this)
Learning may accumulate. Commitment must be renewed.
This governs: • skills • documents • coaching • restarts • AI behavior
⸻
If you want, the next safe move would be to encode this spec as comments next to the mode system, not change behavior yet.
This system is now conceptually closed.