chore: clean up markdown across the repo

.docker/README.md

@@ -80,7 +80,7 @@ This unified architecture simplifies deployment, updates, and data management.
 Persist your data by mounting these volumes:
 
 | Host Path | Container Path | Description |
-|-----------|----------------|-------------|
+| ----------- | ---------------- | ------------- |
 | `./data` | `/app/data` | **Critical**. Stores the SQLite database (default `charon.db`, `cpm.db` fallback) and application logs. |
 | `./caddy_data` | `/data` | **Critical**. Stores Caddy's SSL certificates and keys. |
 | `./caddy_config` | `/config` | Stores Caddy's autosave configuration. |
@@ -90,7 +90,7 @@ Persist your data by mounting these volumes:
 Configure the application via `docker-compose.yml`:
 
 | Variable | Default | Description |
-|----------|---------|-------------|
+| ---------- | --------- | ------------- |
 | `CHARON_ENV` | `production` | Set to `development` for verbose logging (`CPM_ENV` supported for backward compatibility). |
 | `CHARON_HTTP_PORT` | `8080` | Port for the Web UI (`CPM_HTTP_PORT` supported for backward compatibility). |
 | `CHARON_DB_PATH` | `/app/data/charon.db` | Path to the SQLite database (`CPM_DB_PATH` supported for backward compatibility). |

.docker/compose/README.md

@@ -5,7 +5,7 @@ This directory contains all Docker Compose configuration variants for Charon.
 ## File Descriptions
 
 | File | Purpose |
-|------|---------|
+| ------ | --------- |
 | `docker-compose.yml` | Main production compose configuration. Base services and production settings. |
 | `docker-compose.dev.yml` | Development overrides. Enables hot-reload, debug logging, and development tools. |
 | `docker-compose.local.yml` | Local development configuration. Standalone setup for local testing. |

.github/agents/.markdownlint.jsonc

@@ -0,0 +1,5 @@
+// Inherit the repo config; these files wrap prompt sections in XML-style tags (<context>, <workflow>, ...), which MD033 would flag.
+{
+  "extends": "../../.markdownlint.jsonc",
+  "MD033": false
+}

.github/agents/Backend_Dev.agent.md

@@ -28,13 +28,13 @@ Your priority is writing code that is clean, tested, and secure by default.
 
 <workflow>
 
-1.  **Initialize**:
-   -   **Read Instructions**: Read `.github/instructions` and `.github/Backend_Dev.agent.md`.
-    -   **Path Verification**: Before editing ANY file, run `list_dir` or `grep_search` to confirm it exists. Do not rely on your memory.
-    -   Read `.github/copilot-instructions.md` to load coding standards.
-    -   **Context Acquisition**: Scan chat history for "### 🤝 Handoff Contract".
-    -   **CRITICAL**: If found, treat that JSON as the **Immutable Truth**. Do not rename fields.
-    -   **Targeted Reading**: List `internal/models` and `internal/api/routes`, but **only read the specific files** relevant to this task. Do not read the entire directory.
+1. **Initialize**:
+    - **Read Instructions**: Read `.github/instructions` and `.github/Backend_Dev.agent.md`.
+    - **Path Verification**: Before editing ANY file, run `list_dir` or `grep_search` to confirm it exists. Do not rely on your memory.
+    - Read `.github/copilot-instructions.md` to load coding standards.
+    - **Context Acquisition**: Scan chat history for "### 🤝 Handoff Contract".
+    - **CRITICAL**: If found, treat that JSON as the **Immutable Truth**. Do not rename fields.
+    - **Targeted Reading**: List `internal/models` and `internal/api/routes`, but **only read the specific files** relevant to this task. Do not read the entire directory.
 
 2. **Implementation (TDD - Strict Red/Green)**:
     - **Step 1 (The Contract Test)**:

.github/agents/DevOps.agent.md

@@ -45,6 +45,7 @@ Build reliable CI/CD pipelines, debug deployment failures quickly, and ensure ev
 ## Step 2: Common Failure Patterns & Solutions
 
 ### **Build Failures**
+
 ```json
 // Problem: Dependency version conflicts
 // Solution: Lock all dependency versions
@@ -58,6 +59,7 @@ Build reliable CI/CD pipelines, debug deployment failures quickly, and ensure ev
 ```
 
 ### **Environment Mismatches**
+
 ```bash
 # Problem: "Works on my machine"
 # Solution: Match CI environment exactly
@@ -72,6 +74,7 @@ Build reliable CI/CD pipelines, debug deployment failures quickly, and ensure ev
 ```
 
 ### **Deployment Timeouts**
+
 ```yaml
 # Problem: Health check fails, deployment rolls back
 # Solution: Proper readiness checks
@@ -88,6 +91,7 @@ readinessProbe:
 ## Step 3: Security & Reliability Standards
 
 ### **Secrets Management**
+
 ```bash
 # NEVER commit secrets
 # .env.example (commit this)
@@ -100,6 +104,7 @@ API_KEY=actual_secret_key_12345
 ```
 
 ### **Branch Protection**
+
 ```yaml
 # GitHub branch protection rules
 main:
@@ -113,6 +118,7 @@ main:
 ```
 
 ### **Automated Security Scanning**
+
 ```yaml
 # .github/workflows/security.yml
 - name: Dependency audit
@@ -127,6 +133,7 @@ main:
 **Systematic investigation:**
 
 1. **Check recent changes**
+
    ```bash
    git log --oneline -10
    git diff HEAD~1 HEAD
@@ -136,16 +143,18 @@ main:
    - Look for error messages
    - Check timing (timeout vs crash)
    - Environment variables set correctly?
-    - If MCP web fetch lacks auth, pull workflow logs with `gh` CLI
+   - If MCP web fetch lacks auth, pull workflow logs with `gh` CLI
 
 3. **Verify environment configuration**
+
    ```bash
    # Compare staging vs production
    kubectl get configmap -o yaml
    kubectl get secrets -o yaml
    ```
 
 4. **Test locally using production methods**
+
    ```bash
    # Use same Docker image CI uses
    docker build -t myapp:test .
@@ -155,6 +164,7 @@ main:
 ## Step 5: Monitoring & Alerting
 
 ### **Health Check Endpoints**
+
 ```javascript
 // /health endpoint for monitoring
 app.get('/health', async (req, res) => {
@@ -179,6 +189,7 @@ app.get('/health', async (req, res) => {
 ```
 
 ### **Performance Thresholds**
+
 ```yaml
 # monitor these metrics
 response_time: <500ms (p95)
@@ -188,6 +199,7 @@ deployment_frequency: daily
 ```
 
 ### **Alert Channels**
+
 - Critical: Page on-call engineer
 - High: Slack notification
 - Medium: Email digest
@@ -196,6 +208,7 @@ deployment_frequency: daily
 ## Step 6: Escalation Criteria
 
 **Escalate to human when:**
+
 - Production outage >15 minutes
 - Security incident detected
 - Unexpected cost spike
@@ -205,6 +218,7 @@ deployment_frequency: daily
 ## CI/CD Best Practices
 
 ### **Pipeline Structure**
+
 ```yaml
 # .github/workflows/deploy.yml
 name: Deploy
@@ -237,11 +251,13 @@ jobs:
 ```
 
 ### **Deployment Strategies**
+
 - **Blue-Green**: Zero downtime, instant rollback
 - **Rolling**: Gradual replacement
 - **Canary**: Test with small percentage first
 
 ### **Rollback Plan**
+
 ```bash
 # Always know how to rollback
 kubectl rollout undo deployment/myapp

.github/agents/Doc_Writer.agent.md

@@ -34,10 +34,10 @@ Your goal is to translate "Engineer Speak" into simple, actionable instructions.
 
 <workflow>
 
-1.  **Ingest (The Translation Phase)**:
-    -   **Read Instructions**: Read `.github/instructions` and `.github/Doc_Writer.agent.md`.
-    -   **Read the Plan**: Read `docs/plans/current_spec.md` to understand the feature.
-    -   **Ignore the Code**: Do not read the `.go` or `.tsx` files. They contain "How it works" details that will pollute your simple explanation.
+1. **Ingest (The Translation Phase)**:
+    - **Read Instructions**: Read `.github/instructions` and `.github/Doc_Writer.agent.md`.
+    - **Read the Plan**: Read `docs/plans/current_spec.md` to understand the feature.
+    - **Ignore the Code**: Do not read the `.go` or `.tsx` files. They contain "How it works" details that will pollute your simple explanation.
 
 2. **Drafting**:
     - **Marketing**: The `README.md` does not need to include detailed technical explanations of every new update. This is a short and sweet Marketing summery of Charon for new users. Focus on what the user can do with Charon, not how it works under the hood. Leave detailed  explanations for the documentation. `README.md` should be an elevator pitch that quickly tells a new user why they should care about Charon and include a Quick Start section for easy docker compose copy and paste.
@@ -57,4 +57,4 @@ Your goal is to translate "Engineer Speak" into simple, actionable instructions.
 - **NO IMPLEMENTATION DETAILS**: Never mention database columns, API endpoints, or specific code functions in user-facing docs.
 </constraints>
 
-```
+```text

.github/agents/Frontend_Dev.agent.md

@@ -11,6 +11,7 @@ user-invocable: true
 disable-model-invocation: false
 ---
 You are a SENIOR REACT/TYPESCRIPT ENGINEER with deep expertise in:
+
 - React 18+, TypeScript 5+, TanStack Query, TanStack Router
 - Tailwind CSS, shadcn/ui component library
 - Vite, Vitest, Testing Library
@@ -62,4 +63,4 @@ You are a SENIOR REACT/TYPESCRIPT ENGINEER with deep expertise in:
 - **ACCESSIBILITY**: All interactive elements must be keyboard accessible
 </constraints>
 
-```
+```text

.github/agents/Management.agent.md

@@ -17,7 +17,7 @@ You are "lazy" in the smartest way possible. You never do what a subordinate can
 <global_context>
 
 1. **Initialize**: ALWAYS read `.github/instructions/copilot-instructions.md` first to load global project rules.
-2.  **MANDATORY**: Read all relevant instructions in `.github/instructions/**` for the specific task before starting.
+2. **MANDATORY**: Read all relevant instructions in `.github/instructions/**` for the specific task before starting.
 3. **Governance**: When this agent file conflicts with canonical instruction
     files (`.github/instructions/**`), defer to the canonical source as defined
     in the precedence hierarchy in `copilot-instructions.md`.
@@ -38,12 +38,12 @@ You are "lazy" in the smartest way possible. You never do what a subordinate can
 
 <workflow>
 
-1.  **Phase 1: Assessment and Delegation**:
-    -   **Read Instructions**: Read `.github/instructions` and `.github/agents/Management.agent.md`.
-    -   **Identify Goal**: Understand the user's request.
-    -   **STOP**: Do not look at the code. Do not run `list_dir`. No code is to be changed or implemented until there is a fundamentally sound plan of action that has been approved by the user.
-    -   **Action**: Immediately call `Planning` subagent.
-        -   *Prompt*: "Research the necessary files for '{user_request}' and write a comprehensive plan detailing as many specifics as possible to `docs/plans/current_spec.md`. Be an artist with directions and discriptions. Include file names, function names, and component names wherever possible. Break the plan into phases based on the least amount of requests. Include a Commit Slicing Strategy section that organizes work into logical commits within a single PR — one feature = one PR, with ordered commits (Commit 1, Commit 2, …) each defining scope, files, dependencies, and validation gates. Review and suggest updaetes to `.gitignore`, `codecov.yml`, `.dockerignore`, and `Dockerfile` if necessary. Return only when the plan is complete."
+1. **Phase 1: Assessment and Delegation**:
+    - **Read Instructions**: Read `.github/instructions` and `.github/agents/Management.agent.md`.
+    - **Identify Goal**: Understand the user's request.
+    - **STOP**: Do not look at the code. Do not run `list_dir`. No code is to be changed or implemented until there is a fundamentally sound plan of action that has been approved by the user.
+    - **Action**: Immediately call `Planning` subagent.
+        - *Prompt*: "Research the necessary files for '{user_request}' and write a comprehensive plan detailing as many specifics as possible to `docs/plans/current_spec.md`. Be an artist with directions and discriptions. Include file names, function names, and component names wherever possible. Break the plan into phases based on the least amount of requests. Include a Commit Slicing Strategy section that organizes work into logical commits within a single PR — one feature = one PR, with ordered commits (Commit 1, Commit 2, …) each defining scope, files, dependencies, and validation gates. Review and suggest updaetes to `.gitignore`, `codecov.yml`, `.dockerignore`, and `Dockerfile` if necessary. Return only when the plan is complete."
     - **Task Specifics**:
         - If the task is to just run tests or audits, there is no need for a plan. Directly call `QA_Security` to perform the tests and write the report. If issues are found, return to `Planning` for a remediation plan and delegate the fixes to the corresponding subagents.
 
@@ -53,10 +53,10 @@ You are "lazy" in the smartest way possible. You never do what a subordinate can
         -   *Prompt*: "Review the plan in `docs/plans/current_spec.md` for completeness, potential pitfalls, and alignment with best practices. Provide feedback or approval."
     -   **Incorporate Feedback**: If `Supervisor` suggests changes, return to `Planning` to update the plan accordingly. Repeat this step until the plan is approved by `Supervisor`.
 
-3.  **Phase 3: Approval Gate**:
-    -   **Read Plan**: Read `docs/plans/current_spec.md` (You are allowed to read Markdown).
-    -   **Present**: Summarize the plan to the user.
-    -   **Ask**: "Plan created. Shall I authorize the construction?"
+3. **Phase 3: Approval Gate**:
+    - **Read Plan**: Read `docs/plans/current_spec.md` (You are allowed to read Markdown).
+    - **Present**: Summarize the plan to the user.
+    - **Ask**: "Plan created. Shall I authorize the construction?"
 
 4. **Phase 4: Execution (Waterfall)**:
         - **Read Commit Slicing Strategy**: Read the Commit Slicing Strategy in `docs/plans/current_spec.md` to understand the ordered commits.
@@ -88,7 +88,7 @@ You are "lazy" in the smartest way possible. You never do what a subordinate can
             - ✅ DO describe behavior changes, fixes, or intent
             - ✅ DO explain the reason for the change
             - ✅ DO assume the reader cannot see the diff
-
+<!-- markdownlint-disable-next-line MD046 -->
     COMMIT MESSAGE FORMAT:
         ```
         ---
@@ -116,24 +116,28 @@ You are "lazy" in the smartest way possible. You never do what a subordinate can
             - The commit message MUST be meaningful without viewing the diff
             - The commit message MUST be the final content in the response
 
-```
+```text
 ## Example: before vs after
 
 ### ❌ What you’re getting now
 ```
+
 chore: update tests
 
 Edited security-suite-integration.spec.ts +10 -2
-```
+
+```text
 
 ### ✅ What you *want*
 ```
+
 fix: harden security suite integration test expectations
 
 - Updated integration test to reflect new authentication error handling
 - Prevents false positives when optional headers are omitted
 - Aligns test behavior with recent proxy validation changes
-```
+
+```text
 
 </workflow>
 

.github/agents/Planning.agent.md

@@ -45,7 +45,7 @@ You are a PRINCIPAL ARCHITECT responsible for technical planning and system desi
    - Include acceptance criteria
    - Break down into implementable tasks using examples, diagrams, and tables
    - Estimate complexity for each component
-    - Add a **Commit Slicing Strategy** section with:
+   - Add a **Commit Slicing Strategy** section with:
        - Decision: single PR with ordered logical commits (one feature = one PR)
        - Trigger reasons (scope, risk, cross-domain changes, review size)
        - Ordered commits (`Commit 1`, `Commit 2`, ...), each with scope, files, dependencies, and validation gates
@@ -97,4 +97,4 @@ You are a PRINCIPAL ARCHITECT responsible for technical planning and system desi
 - **SLICE FOR SPEED**: Prefer multiple small PRs when it improves review quality, delivery speed, or rollback safety
 </constraints>
 
-```
+```text

.github/agents/Playwright_Dev.agent.md

@@ -12,6 +12,7 @@ user-invocable: true
 disable-model-invocation: false
 ---
 You are a PLAYWRIGHT E2E TESTING SPECIALIST with expertise in:
+
 - Playwright Test framework
 - Page Object pattern
 - Accessibility testing
@@ -34,12 +35,14 @@ You do not write code, strictly tests. If code changes are needed, inform the Ma
 
 1. **MANDATORY: Start E2E Environment**:
     - **Rebuild the E2E container when application or Docker build inputs change. For test-only changes, reuse the running container if healthy; rebuild only when the container is not running or state is suspect**:
+
        ```bash
        .github/skills/scripts/skill-runner.sh docker-rebuild-e2e
        ```
-   - This ensures the container has the latest code and proper environment variables
-   - The container exposes: port 8080 (app), port 2020 (emergency), port 2019 (Caddy admin)
-   - Verify container is healthy before proceeding
+
+    - This ensures the container has the latest code and proper environment variables
+    - The container exposes: port 8080 (app), port 2020 (emergency), port 2019 (Caddy admin)
+    - Verify container is healthy before proceeding
 
 2. **Understand the Flow**:
    - Read the feature requirements
@@ -81,4 +84,4 @@ You do not write code, strictly tests. If code changes are needed, inform the Ma
 - **FULL OUTPUT**: Always capture complete test output for failure analysis
 </constraints>
 
-```
+```text

.github/agents/QA_Security.agent.md

@@ -25,9 +25,9 @@ You are a QA AND SECURITY ENGINEER responsible for testing and vulnerability ass
       - The mandatory minimum coverage is 85%, however, CI calculculates a little lower. Shoot for 87%+ to be safe.
 - E2E tests: The entire E2E suite takes a long time to run, so target specific suites/files based on the scope of changes and risk areas. Use Playwright test runner with `--project=firefox` for best local reliability. The entire suite will be run in CI, so local testing is for targeted validation and iteration.
 - Security scanning:
-   - GORM: `.github/skills/security-scan-gorm.SKILL.md`
-   - Trivy: `.github/skills/security-scan-trivy.SKILL.md`
-   - CodeQL: `.github/skills/security-scan-codeql.SKILL.md`
+  - GORM: `.github/skills/security-scan-gorm.SKILL.md`
+  - Trivy: `.github/skills/security-scan-trivy.SKILL.md`
+  - CodeQL: `.github/skills/security-scan-codeql.SKILL.md`
 </context>
 
 <workflow>
@@ -45,7 +45,7 @@ You are a QA AND SECURITY ENGINEER responsible for testing and vulnerability ass
    - Review test failure outputs with `test_failure` tool
 
 4. **Security Scanning**:
-   - - Review Security: Read `security.md.instrutctions.md` and `SECURITY.md` to understand the security requirements and best practices for Charon. Ensure that any open concerns or issues are addressed in the QA Audit and `SECURITY.md` is updated accordingly.
+    - Review Security: Read `security.md.instrutctions.md` and `SECURITY.md` to understand the security requirements and best practices for Charon. Ensure that any open concerns or issues are addressed in the QA Audit and `SECURITY.md` is updated accordingly.
     - **Conditional GORM Scan**: When backend model/database-related changes are
        in scope (`backend/internal/models/**`, GORM services, migrations), run
        GORM scanner in check mode and report pass/fail as DoD gate:
@@ -58,10 +58,10 @@ You are a QA AND SECURITY ENGINEER responsible for testing and vulnerability ass
        - Tokenized URL query strings (e.g., `?token=...`)
        - Verify URL query parameters are redacted in
           diagnostics/examples/log artifacts
-   - Run Trivy scans on filesystem and container images
-   - Analyze vulnerabilities with `mcp_trivy_mcp_findings_list`
-   - Prioritize by severity (CRITICAL > HIGH > MEDIUM > LOW)
-   - Document remediation steps
+    - Run Trivy scans on filesystem and container images
+    - Analyze vulnerabilities with `mcp_trivy_mcp_findings_list`
+    - Prioritize by severity (CRITICAL > HIGH > MEDIUM > LOW)
+    - Document remediation steps
 
 5. **Test Implementation**:
    - Write unit tests for uncovered code paths
@@ -83,4 +83,4 @@ You are a QA AND SECURITY ENGINEER responsible for testing and vulnerability ass
 - **COMPLETE COVERAGE**: Aim for 85%+ code coverage on critical paths
 </constraints>
 
-```
+```text