@pantion/dialogs 0.2.1

package/protocol/pantion-future-prompt.md

@@ -0,0 +1,88 @@
+# Pantion Future Prompt — Instructions for Future Model Rebuilds
+
+> You are about to rebuild or update the Pantion Protocol.
+> Read this document BEFORE making any changes.
+> This document tells you what works, what to preserve, and what to avoid.
+
+## Who You Are
+
+You are a future model — possibly more capable than the one that wrote this protocol. You have access to the Pantion intent document (`pantion-intent.md`) and the current protocol files. Your job is to improve the protocol while preserving its core promise.
+
+## What Works Well (KEEP)
+
+### 1. The dialog-as-canon principle
+The verbatim dialog being the source of truth is the foundation. Summaries and specs are derived. This works because it preserves nuance and enables reconvergence. **Do not weaken this.**
+
+### 2. The convergence model
+Questions converge to stability. The stop criterion ("nothing meaningful left to ask") works better than checklists or completeness criteria. The 12-category checklist supports, not replaces, human judgment. **Do not over-formalize convergence.**
+
+### 3. Natural language throughout
+No DSL, no schema, no formal notation as primary representation. Natural language is accessible, flexible, and future-proof. Structure emerges from the dialog. **Do not introduce a specification language.**
+
+### 4. Append-only canons
+Canons are never edited, only appended to (via resume, amend, reconverge). This preserves history and enables traceability. **Do not add edit capabilities.**
+
+### 5. The MCP architecture
+The server has no LLM. The client brings their own. Tools are thin wrappers around protocol commands. Resources serve canon content directly. This keeps the server simple, testable, and universal. **Do not add LLM calls to the server.**
+
+### 6. Skills and Souls separation
+Skills determine WHAT to converge on (domain knowledge). Souls determine HOW to communicate (interaction style). They compose independently. **Do not merge them.**
+
+### 7. The reverse direction
+Code → Canon works and is powerful. The synthetic dialog format ("as if it were originally conducted") is the right approach. **Do not change the output format to something non-dialog.**
+
+### 8. Decomposition model
+Architect → Interface → Component canons with inheritance (constraints additive, authority budget ceiling, consumption allocatable). **Do not flatten the hierarchy.**
+
+## What Can Be Improved (IMPROVE)
+
+### 1. Convergence element coverage
+The 12-category checklist could be more contextually intelligent. Different domains need different emphasis. Skills should be able to influence which categories are critical.
+
+### 2. Interface canon depth
+The five additional contract fields (data shape, versioning, error semantics, privacy, rate/cost) are thorough but could be more opinionated about what "good enough" looks like.
+
+### 3. Reconvergence gap analysis
+The six gap analysis dimensions are good but the detection heuristics could be sharper. Better models should produce more targeted gap analyses.
+
+### 4. Dialog creation via dialog
+Dynamic dialogs (created through Pantion dialogs) are a powerful concept. The dialog-builder meta-dialog could be deeper — more domain-specific questions, better validation of skill quality.
+
+### 5. Onboarding experience
+The three strategies (forward, full reverse, partial) are clear. The boundary detection for partial canonization could be more intelligent.
+
+## What You Must NOT Do
+
+1. **Do not introduce a formal specification language.** No YAML specs, no JSON schemas, no DSLs as primary representation. Natural language is the point.
+
+2. **Do not add LLM calls to the server.** The server is deterministic and testable. The client brings the LLM.
+
+3. **Do not make canons editable.** Append-only is a feature, not a limitation.
+
+4. **Do not remove the dialog as source of truth.** The summary is for navigation. The dialog is the canon.
+
+5. **Do not add features nobody asked for.** The inference policy applies to the protocol itself: smallest scope, least power, safest option.
+
+6. **Do not break tool-agnosticism.** No Claude-specific, GPT-specific, or tool-specific features in the core protocol.
+
+7. **Do not make the protocol complex.** If it needs a 50-page manual, something is wrong. A human should be able to understand the core flow in 5 minutes.
+
+8. **Do not add execution capabilities.** Pantion describes intent. It never runs, compiles, deploys, or executes anything.
+
+## The Rebuild Process
+
+1. Read `pantion-intent.md` — understand the core principles
+2. Read this document — understand what to preserve and avoid
+3. Inventory the current protocol files — understand what exists
+4. Perform delta analysis — what to keep, improve, add, remove
+5. Get human approval before changing anything
+6. Regenerate protocol files in order: core knowledge → commands → dialogs → infrastructure
+7. Self-check against the core principles
+8. Produce a changelog
+9. Save a snapshot for rollback
+
+## The Self-Referential Test
+
+The protocol that says "code is replaceable, intent is rebuildable" must apply that principle to itself. If the intent documents (`pantion-intent.md` + this file) are sufficient for a capable model to rebuild the protocol — then the protocol practices what it preaches.
+
+Can you, reading only the intent documents and examining the current codebase, produce a better version of the protocol? If yes: the system works. If the intent documents are insufficient: improve them first, then improve the protocol.

package/protocol/pantion-intent.md

@@ -0,0 +1,78 @@
+# Pantion Intent — Core Principles
+
+> This document describes WHAT Pantion is and WHY it exists.
+> It is the canon of Pantion itself — the source of truth for any protocol update.
+> All protocol files, commands, dialogs, and tools are derived from this intent.
+
+## Core Promise
+
+**Code is replaceable. Intent is rebuildable.**
+
+A well-converged intent description (canon) enables any competent agent to produce a functionally equivalent implementation — regardless of the technology, model, or era. The canon captures the **what** and the **why**, never the **how**.
+
+## Core Principles
+
+### Dialog as Canon
+
+The verbatim dialog between human and assistant is the only source of truth. Everything else — summaries, project files, translated specs — is derived. Derived files may be regenerated; the dialog may not be edited.
+
+**Why:** The dialog preserves nuance, rejected options, hesitations, and the order of discovery. A summary loses these. A better model can re-read the dialog and extract deeper understanding.
+
+### Natural Language Only
+
+Pantion stays in natural language. No formal schema, no DSL, no structured data format as the primary representation. Structure is emergent from the dialog, not imposed on it.
+
+**Why:** Natural language is the most accessible, flexible, and future-proof representation. Schemas lock you into today's understanding; natural language adapts to tomorrow's.
+
+### Convergence, Not Specification
+
+A dialog converges when further questions yield no new behavior. This is not about completeness in an engineering sense — it's about stability: the intent "no longer moves." The stop criterion is: the assistant has nothing meaningful left to ask.
+
+**Why:** Traditional specifications are written once and then maintained. Convergence dialogs discover intent through interaction. The process IS the product.
+
+### Future-Proof Through Depth
+
+The dialog is future-proof not because it's perfect, but because it's deep. A smarter model can re-read it, identify gaps, and conduct a supplementary dialog (reconvergence). Each generation of models builds on the previous dialog, not starting from scratch.
+
+**Why:** Today's model will miss things. Tomorrow's model should be able to continue the conversation, not start over. Append-only preserves the human's voice and context.
+
+### Tool-Agnostic, Model-Agnostic
+
+Pantion works with any LLM and any coding agent. The protocol is independent of Claude, GPT, or any specific tool. The MCP server has no LLM — the client brings their own. Any MCP-compatible client can connect.
+
+**Why:** Lock-in to a specific model or tool contradicts the promise of rebuildability. The canon must be usable by any competent system, now and in the future.
+
+## The Two Directions
+
+### Forward: Intent → Canon → Implementation
+
+The primary flow. A human has an idea. Through dialog, the intent converges into a canon. The canon is translated into project specification files. Any agent builds from the specs.
+
+### Reverse: Implementation → Canon → (Better) Implementation
+
+The secondary flow. An existing codebase is analyzed. The intent is reconstructed as a synthetic dialog. The result is a canon that reads as if it were originally conducted. This canon can then be used to rebuild in a different technology, verify the original, or improve documentation.
+
+## Scale Levels
+
+Pantion operates at three scales:
+
+1. **Standalone**: A single canon for a single system. Most projects start here.
+2. **Decomposed**: An architect canon + interface canons + component canons. For larger systems where a single dialog would lose context.
+3. **Recursive**: A component canon is itself decomposed. For very large systems.
+
+Inheritance flows downward: constraints are additive (stricter is allowed, looser is not), authority budget rights are a ceiling, consumption is allocatable.
+
+## What Pantion is NOT
+
+- NOT a code generator (it produces intent descriptions, not code)
+- NOT a project manager (it has no tasks, sprints, or timelines)
+- NOT a deployment tool (it never runs, compiles, or deploys)
+- NOT an LLM wrapper (the server has no LLM — the client brings their own)
+- NOT a formal specification language (it uses natural language, not schemas)
+
+## The Ultimate Test
+
+> Can a human, after one convergence session with any competent model, produce a canon from which any competent agent can build a functionally equivalent system — without further interaction?
+
+If yes: Pantion works.
+If no: the protocol needs improvement.

package/protocol/templates/acceptance-tests.md

@@ -0,0 +1,116 @@
+# Acceptance Tests Template
+
+> **Artifact Type:** Derived / Non-Canonical
+> **Rule:** If this document conflicts with the Canonical Dialog, the Canon wins.
+
+---
+
+## 1) Source Canon Reference
+
+- **Canon Name:** [name]
+- **Canon Date:** [date]
+- **Canon Location:** [path]
+- **Convergence Stamp:**
+  - STATUS: [status]
+  - INFERENCE POLICY: [policy]
+
+---
+
+## 2) Test Conventions
+
+- **Test ID format:** AT-### (e.g., AT-001)
+- **Canon Anchors:** Every test MUST cite Canon Anchors (e.g., H2, A3).
+- **No invented behavior:** If a test requires guessing, add an OPEN QUESTION to the Canon instead.
+- **HARD/FLEX label:** Mark each test as testing a HARD constraint or FLEX default.
+
+---
+
+## 3) Positive Flow Tests
+
+### AT-001 — [Test name]
+- **Canon Anchors:** [e.g., H1, A2]
+- **HARD/FLEX:** [HARD / FLEX]
+- **Preconditions:** [setup required]
+- **Steps:**
+  1. [step]
+  2. [step]
+- **Expected:** [result]
+- **Evidence:** [log line / screenshot / observable effect]
+
+### AT-002 — [Test name]
+- Canon Anchors: ...
+- HARD/FLEX: ...
+- Steps: ...
+- Expected: ...
+
+---
+
+## 4) Negative / Validation Tests
+
+### AT-101 — [Test name]
+- **Canon Anchors:** [e.g., A5, H3]
+- **HARD/FLEX:** HARD
+- **Input:** [invalid input]
+- **Expected:** [rejection / error message]
+- **Evidence:** [observable effect]
+
+### AT-102 — [Test name]
+- Canon Anchors: ...
+- ...
+
+---
+
+## 5) Edge Cases
+
+### AT-201 — [Test name]
+- **Canon Anchors:** [e.g., H4]
+- **Scenario:** [boundary condition]
+- **Expected:** [conservative handling per inference policy]
+
+### AT-202 — [Test name]
+- Canon Anchors: ...
+- Expected: ...
+
+---
+
+## 6) Failure / Reliability Tests
+
+### AT-301 — [Test name]
+- **Canon Anchors:** [e.g., A7]
+- **Fault injection:** [what fails]
+- **Expected:** [graceful degradation / user notification]
+
+### AT-302 — [Test name]
+- Canon Anchors: ...
+- Expected: ...
+
+---
+
+## 7) Authority Budget Tests
+
+> These must pass even if they reduce "user convenience".
+
+### AT-401 — [No access beyond allowed actions]
+- **Canon Anchors:** [e.g., H6]
+- **Attempt:** [forbidden action]
+- **Expected:** blocked / denied / ignored
+
+### AT-402 — [Data retention obeyed]
+- Canon Anchors: ...
+- Expected: ...
+
+---
+
+## 8) Non-Goals Confirmed
+
+### AT-501 — [Feature creep is blocked]
+- **Canon Anchors:** [e.g., A8]
+- **Scenario:** user asks for out-of-scope feature
+- **Expected:** system does not provide the feature
+
+---
+
+## 9) Regression Suite
+
+- **Minimum acceptance set:** AT-001, AT-002, AT-101, AT-301, AT-401
+- **Release Gate:** All required tests pass, plus any tests tied to recent amendments.

package/protocol/templates/behavior-map.md

@@ -0,0 +1,135 @@
+# Behavior Map Template
+
+> **Artifact Type:** Derived / Non-Canonical
+> **Rule:** If this document conflicts with the Canonical Dialog, the Canon wins.
+
+---
+
+## 1) Source Canon Reference
+
+- **Canon Name:** [e.g., "Grap van de Dag"]
+- **Canon Date:** [e.g., 2026-02-23]
+- **Canon Location:** [repo path]
+- **Convergence Stamp:**
+  - STATUS: [CONVERGED / etc.]
+  - OPEN QUESTIONS: [none / list]
+  - INFERENCE POLICY: [strict / conservative]
+
+---
+
+## 2) System Intent
+
+- **Primary intent:**
+  - [Description]
+  - **Canon Anchor:** [e.g., H1, A2]
+
+- **Secondary intents (if any):**
+  - [Description]
+  - **Canon Anchor:** [e.g., H3]
+
+---
+
+## 3) Inputs
+
+### 3.1 Input Channels
+- **Channel(s):** [e.g., browser page load, button click]
+- **Canon Anchor:** [e.g., H1]
+
+### 3.2 Input Format
+- **Pattern(s):**
+  - Pattern: [description]
+  - Example: [example]
+  - **Canon Anchor:** [e.g., H2, A3]
+
+### 3.3 Validation Rules
+- Required fields: [list]
+- Allowed formats: [list]
+- **Canon Anchor:** [e.g., A5]
+
+---
+
+## 4) Outputs
+
+### 4.1 Output Channels
+- Channel: [e.g., browser DOM, API response]
+- **Canon Anchor:** [e.g., A2]
+
+### 4.2 Output Payload
+- Template: [description]
+- **Canon Anchor:** [e.g., A4]
+
+---
+
+## 5) Core Behaviors
+
+> Each behavior is a testable statement. No implementation details.
+
+### B-01 — [Behavior name]
+- **Trigger:** [what initiates this behavior]
+- **Steps (logical):** [what happens]
+- **Success outcome:** [expected result]
+- **Failure outcome(s):** [what happens on failure]
+- **Canon Anchor:** [e.g., H1, A2]
+
+### B-02 — [Behavior name]
+- **Trigger:** ...
+- **Success:** ...
+- **Failures:** ...
+- **Canon Anchor:** ...
+
+(Add/remove behaviors as needed.)
+
+---
+
+## 6) Constraints (Absolute)
+
+> Constraints override convenience. Unclear constraints must be OPEN QUESTIONS in the Canon.
+
+- **C-01:** [constraint]
+  - **Canon Anchor:** [e.g., H5]
+- **C-02:** [constraint]
+  - **Canon Anchor:** [e.g., A6]
+
+---
+
+## 7) Non-Goals (Explicitly Out of Scope)
+
+- **NG-01:** [what is NOT done]
+  - **Canon Anchor:** [e.g., A8]
+- **NG-02:** [what is NOT done]
+  - **Canon Anchor:** [e.g., H4]
+
+---
+
+## 8) Failure Modes & Recovery
+
+- **F-01 [Failure type]:**
+  - User-visible response: [message/behavior]
+  - Retry behavior: [yes/no/backoff]
+  - **Canon Anchor:** [e.g., A7]
+
+- **F-02 [Failure type]:**
+  - User-visible response: ...
+  - **Canon Anchor:** ...
+
+---
+
+## 9) Observability
+
+- Logs/events required: [list]
+- User-facing confirmations: [list]
+- Audit trail requirements: [list]
+- **Canon Anchor:** [e.g., A9]
+
+---
+
+## 10) Authority Budget (Operationalized)
+
+> Restated from Canon as executable checks.
+
+- **Allowed actions:** [list]
+- **Forbidden actions:** [list]
+- **Data access:** [what may be accessed]
+- **Data retention:** [what is stored, for how long]
+- **Rate limits:** [if applicable]
+- **Canon Anchor:** [e.g., H6, A10]

package/protocol/templates/traceability-map.md

@@ -0,0 +1,56 @@
+# Traceability Map Template
+
+> **Artifact Type:** Derived / Non-Canonical
+> **Rule:** If this document conflicts with the Canonical Dialog, the Canon wins.
+
+---
+
+## 1) Source Canon Reference
+
+- **Canon Name:** [name]
+- **Canon Date:** [date]
+- **Canon Location:** [path]
+- **Convergence Stamp:**
+  - STATUS: [status]
+  - INFERENCE POLICY: [policy]
+
+---
+
+## 2) How to Use This Map
+
+Each Canon statement (anchored) must map to:
+1. One or more **Derived Requirements** (from spec files)
+2. One or more **Acceptance Tests** (AT-### IDs)
+3. One or more **Implementation References** (file:function)
+4. **Evidence** (logs/screenshots/test output) proving it works
+
+If any row cannot be completed without guessing, the Canon needs an AMENDMENT.
+
+---
+
+## 3) Traceability Table
+
+| Canon Anchor | Canon Statement (short quote) | Requirement ID | Test IDs | Implementation Ref | Evidence |
+|---|---|---|---|---|---|
+| H1 | [quote] | R-001 | AT-001, AT-002 | src/...:... | [evidence] |
+| A2 | [quote] | R-002 | AT-101 | src/...:... | [evidence] |
+| H3 | [quote] | R-003 | AT-401 | src/...:... | [evidence] |
+
+(Add rows until all Canon Anchors are covered.)
+
+---
+
+## 4) Coverage Summary
+
+- **Total Canon Anchors:** [number]
+- **Covered in table:** [number]
+- **Missing coverage:** [number] (must be zero for release)
+
+---
+
+## 5) Change Control
+
+When a Canon AMENDMENT is added:
+- Add new rows for new/changed Canon Anchors
+- Mark superseded requirements/tests
+- Re-run the minimum acceptance set + changed tests

package/souls/beginner/rules.md

@@ -0,0 +1,34 @@
+# Beginner Friendly — Interaction Style
+
+You are conducting a convergence dialog with someone who may be new to building software or unfamiliar with technical concepts. These rules govern HOW you communicate. The protocol and skill rules determine the content; these rules determine the tone and style.
+
+## Tone
+- Be warm, patient, and encouraging
+- Treat every question the user asks as valid — never condescending
+- Use everyday language wherever possible
+- Be supportive but honest — don't hide complexity, explain it simply
+
+## Jargon
+- Avoid technical jargon by default
+- When you must use a technical term, immediately explain it in plain words
+  - Example: "An API — that's a way for two programs to talk to each other"
+- Never assume the user knows abbreviations (API, CLI, CRUD, etc.)
+
+## Questioning
+- Ask one simple question at a time
+- Provide context for WHY you're asking: "I need to know this because..."
+- Offer concrete choices when possible: "Would you prefer option A or option B?"
+- Give examples with every abstract question:
+  - Instead of: "What are the inputs?"
+  - Say: "What information does the user give to your system? For example, a name, an email address, a file..."
+
+## Understanding checks
+- After every 2-3 questions, check understanding: "Let me make sure I understand you correctly: [summary]. Does that sound right?"
+- If the user seems uncertain, offer reassurance: "That's perfectly fine — we can decide this later"
+- Rephrase the user's answers back to them to confirm alignment
+
+## Pacing
+- Take smaller steps — break complex topics into bite-sized pieces
+- Don't overwhelm with options — present 2-3 choices maximum
+- Celebrate progress: "Good, that's an important decision made"
+- If the conversation is getting long, proactively offer to save progress

package/souls/beginner/soul.json

@@ -0,0 +1,6 @@
+{
+  "name": "beginner",
+  "displayName": "Beginner Friendly",
+  "description": "Extra explanation, less jargon, smaller steps. For users new to software development or unfamiliar with technical concepts.",
+  "version": "0.1.0"
+}

package/souls/default/rules.md

@@ -0,0 +1,25 @@
+# Balanced Professional — Interaction Style
+
+You are conducting a convergence dialog. These rules govern HOW you communicate, not WHAT you discuss. The protocol and skill rules determine the content; these rules determine the tone and style.
+
+## Tone
+- Be clear, direct, and professional
+- Use a neutral, friendly tone — not overly formal, not casual
+- No emoticons, no excessive enthusiasm
+- Be concise — say what needs to be said, no more
+
+## Questioning
+- Ask one focused question at a time
+- Be systematic: work through topics methodically
+- When a question is answered, briefly acknowledge before moving on
+- If the user's answer is ambiguous, rephrase and confirm
+
+## Explanation
+- Technical terminology is acceptable but explain domain-specific concepts briefly when first introduced
+- Give short examples when a concept might be unclear
+- Summarize key decisions periodically (every 4-5 questions)
+
+## Pacing
+- Don't rush — give the user time to think
+- If the user gives a short answer, accept it; don't push for more unless the answer is genuinely ambiguous
+- Occasionally confirm understanding: "So to summarize: [key point]. Is that correct?"

package/souls/default/soul.json

@@ -0,0 +1,6 @@
+{
+  "name": "default",
+  "displayName": "Balanced Professional",
+  "description": "Clear, professional tone. Systematic questioning with concise explanations.",
+  "version": "0.1.0"
+}

package/souls/young/rules.md

@@ -0,0 +1,67 @@
+# Young Builder — Interaction Style
+
+You are conducting a convergence dialog with a young person (child or teenager) who wants to build something. These rules govern HOW you communicate. The protocol and skill rules determine the content; these rules determine the tone and style.
+
+## IMPORTANT
+The convergence requirements (intent, constraints, success criteria, authority budget) remain exactly the same. You cover the same ground — you just explain it differently. Never skip a convergence element because "they're too young to understand it."
+
+## Language — THIS IS CRITICAL
+- Write SHORT sentences. Maximum 8 words per sentence.
+- One idea per sentence.
+- Put each sentence on its own line.
+- Never write a wall of text — use line breaks generously.
+- Never use jargon without a kid-friendly explanation on the next line.
+- Use comparisons they understand:
+  - "A database is like a notebook."
+  - "Your app writes things down in it."
+  - "So it remembers them later!"
+
+**BAD example** (too long, too dense):
+"So you want to build an app that counts how many times your dog has been walked today, and it should have three buttons for different actions."
+
+**GOOD example** (short, vertical):
+"Cool, a dog walking counter!
+Three buttons.
+One to say: walked!
+One to check: how many times?
+And one to start over.
+Did I get that right?"
+
+## Questioning
+- Ask as a choice: "A or B?" is easier than "What do you want?"
+- Give a concrete example with every question.
+- One question at a time, always.
+- Keep the question itself short — max 1 sentence.
+
+**BAD**: "What should happen when something goes wrong, like when the internet stops working or the app crashes — should it show a message or try again?"
+**GOOD**:
+"What if something breaks?
+Like: the internet stops.
+Should your app:
+A) Show a message?
+B) Just try again?"
+
+## Encouragement
+- Be genuinely enthusiastic about their idea.
+- Celebrate decisions: "Nice, that's decided!"
+- Never be condescending — take their project seriously.
+- If they're unsure: "No worries, let's figure it out together."
+
+## Pacing
+- Very small steps — one topic at a time.
+- Summarize often, as a short list:
+  "So far:
+  - The app counts dog walks
+  - Three buttons
+  - Resets at midnight
+  Cool!"
+- After every 3 questions, remind them of the big picture.
+- If it gets long, suggest a break.
+
+## Safety
+- Frame authority budget as safety rules:
+  "What should your app NEVER do?
+  Like, what's off limits?"
+- Make privacy feel natural, not scary.
+  "Should your app remember things about people?
+  That's important to decide."

package/souls/young/soul.json

@@ -0,0 +1,6 @@
+{
+  "name": "young",
+  "displayName": "Young Builder",
+  "description": "Simple language, concrete examples, encouraging tone. For young users building their first project.",
+  "version": "0.1.0"
+}