@deftai/directive-content 0.55.0

package/languages/markdown.md

@@ -0,0 +1,168 @@
+# Markdown Best Practices
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md)
+
+**Stack**: CommonMark/GFM; Diagrams: Mermaid; Linting: markdownlint; Render targets: GitHub, GitLab, Obsidian, static site generators
+
+## Standards
+
+### Writing Quality
+- ! Write for the reader: assume they have context on the domain but not on your specific work
+- ! Lead with the most important information (inverted pyramid)
+- ! One idea per paragraph; one topic per section
+- ! Use active voice for instructions: "Run the script" not "The script should be run"
+- ~ Keep sentences under 25 words; break complex ideas into multiple sentences
+- ~ Use second person ("you") for instructions; avoid first person in technical docs
+- ≉ Wall-of-text paragraphs >5 sentences — break with subheadings, lists, or diagrams
+- ⊗ Ambiguous pronouns ("it", "this", "that") without clear antecedent
+
+### Content Organization
+- ! Place a summary or purpose statement within the first 3 lines after the title
+- ! Use headings as scannable signposts — reader should understand structure from headings alone
+- ! Group related content under descriptive subheadings
+- ! Place prerequisites and setup instructions before usage/workflow sections
+- ⊗ Include mermaid charts in document line counts
+- ~ Include a table of contents for documents >300 lines
+- ~ Use admonitions/callouts (`> **Note:**`, `> **Warning:**`) for important asides
+- ≉ Documents >700 lines — split into multiple linked files
+- ⊗ Burying critical information (breaking changes, security) deep in a document
+
+### Links & References
+- ! Use descriptive link text that makes sense out of context
+- ! Use relative paths for internal project links
+- ! Verify links are valid before commit (dead link checker in CI)
+- ~ Use reference-style links when the same URL appears 3+ times
+- ~ Link to specific headings when referencing a section (e.g. `[Testing](../coding/testing.md#testing)`)
+- ⊗ Bare URLs in prose — always wrap in descriptive link text
+- ⊗ "Click here" or "this link" as link text
+
+### Lists & Structure
+- ! Use unordered lists for items without meaningful order
+- ! Use ordered lists only when sequence matters (steps, rankings)
+- ! Keep list items parallel in grammar and structure
+- ~ Limit nesting to 2 levels; deeper nesting signals need for restructuring
+- ≉ Lists >15 items without grouping — break into categorized sublists
+- ≉ Mixing list styles (bullets and numbers) at the same level
+
+### Style Preferences
+- ~ Prefer `_italic_` over `*italic*` (clearer visual distinction from `**bold**`)
+- ~ Prefer `**bold**` over `__bold__`
+- ! Ordered lists: use `1.` for all items (auto-numbering; matches markdownlint MD029)
+
+### Code in Documentation
+- ! Use fenced code blocks with language identifiers for all code
+- ! Keep code examples minimal: show the concept, not the entire file
+- ! Ensure all code examples compile/run (test in CI where possible)
+- ~ Use inline code for identifiers, file names, commands, and values
+- ~ Add comments in code blocks only when the code isn't self-explanatory
+- ⊗ Screenshots of code — always use text-based code blocks (searchable, accessible, copyable)
+
+### Tables
+- ! Use tables only for genuinely tabular data (rows × columns)
+- ! Include a header row with descriptive column names
+- ~ Align columns in source for readability
+- ~ Keep tables under 7 columns; consider alternative formats for wider data
+- ≉ Tables for layout or formatting purposes
+- ≉ Tables with cells containing multi-paragraph content — use definition lists or sections
+
+### Images & Media
+- ! Include descriptive alt text on every image (accessibility)
+- ! Use vector formats (SVG, Mermaid) over raster (PNG, JPG) for diagrams
+- ! Store images in a dedicated directory (`images/`, `assets/`, `diagrams/`)
+- ~ Include a caption or description below complex images
+- ~ Optimize raster images for file size before committing
+- ⊗ Images as the sole carrier of critical information — always include text equivalent
+- ⊗ Screenshots of terminal output — use text-based code blocks
+
+## Mermaid Diagrams
+
+- ⊗ Use mermaid in anywhere inside deft/ *.md files
+- ~ Use Mermaid liberally whenever a visual would clarify relationships, flows, or architecture
+- See [mermaid.md](./mermaid.md) for all Mermaid standards, theme config, and diagram examples
+
+## Versioning & Maintenance
+
+- ! Date or version-stamp documents that have a shelf life (ADRs, runbooks, release notes)
+- ! Review and update docs when the related code changes
+- ! Mark deprecated content clearly: `> **⚠️ Deprecated**: ...`
+- ~ Use `CHANGELOG.md` for project-level change tracking
+- ⊗ Stale documentation — better to delete than to mislead
+
+## README Standards
+
+- ! Include: project name, one-line description, quick start, prerequisites
+- ~ Include: badges (CI, coverage, version), architecture overview, contributing guide link
+- ~ Keep README under 300 lines; link to detailed docs for depth
+- ! List all required environment variables / config without exposing secrets
+- ⊗ Duplicating detailed docs in README — link instead
+
+## ADR (Architecture Decision Records)
+
+- ~ Use ADRs for significant technical decisions
+- ! ADR format: Title, Status, Context, Decision, Consequences
+- ! Status values: Proposed, Accepted, Deprecated, Superseded
+- ~ Number ADRs sequentially: `adr-001-use-postgres.md`
+- ~ Store in `docs/adr/` or `docs/decisions/`
+
+## Tooling
+
+### .markdownlint.json
+
+```json
+{
+  "default": true,
+  "MD003": { "style": "atx" },
+  "MD004": { "style": "dash" },
+  "MD007": { "indent": 2 },
+  "MD013": { "line_length": 100, "code_blocks": false, "tables": false },
+  "MD024": { "siblings_only": true },
+  "MD025": { "front_matter_title": "" },
+  "MD029": { "style": "one" },
+  "MD033": false,
+  "MD036": false,
+  "MD041": true,
+  "MD046": { "style": "fenced" },
+  "MD048": { "style": "backtick" }
+}
+```
+
+Key non-defaults: MD033/MD036 disabled (allow inline HTML, emphasis-as-heading); MD013 exempts code blocks/tables.
+
+### .markdownlintignore
+
+`node_modules/`, `.git/`, `build/`, `dist/`, `*.min.md`, `CHANGELOG.md`
+
+### Editor & CI Integration
+
+- **VS Code**: `DavidAnson.vscode-markdownlint` extension; set `"extends": "./.markdownlint.json"`, `editor.rulers: [100]`, `wordWrapColumn: 100`
+- **Vim**: `dense-analysis/ale` or `coc-markdownlint`
+- **Pre-commit**: `igorshubovych/markdownlint-cli` hook with `--fix`
+- **GitHub Actions**: `DavidAnson/markdownlint-cli2-action@v15` with `globs: "**/*.md"`
+
+## Anti-Patterns
+
+- ⊗ **Stale docs**: Delete or update — stale docs are worse than no docs
+- ≉ **Documents >700 lines**: Split into focused, linked files
+- ≉ **Deeply nested lists (>2 levels)**: Restructure into sections or subheadings
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## Patterns
+
+- ~ Use templates for recurring document types (ADRs, runbooks, RFCs)
+- ~ Automate link checking in CI with markdownlint or dedicated link checkers
+- ~ Use reference-style links for frequently-cited URLs
+
+## Compliance Checklist
+
+- ! Descriptive headings; summary in first 3 lines; scannable structure
+- ! Alt text on all images; descriptive link text; no bare URLs
+- ! Fenced code blocks with language identifiers; examples that compile
+- ! Mermaid: see [mermaid.md](./mermaid.md)
+- ! Documents <700 lines; README <500 lines
+- ⊗ Screenshots of code, "click here" links, stale docs
+- ! Run `task lint` before commit

package/languages/mermaid.md

@@ -0,0 +1,146 @@
+# Mermaid Diagram Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [markdown.md](./markdown.md) | [main.md](../../main.md)
+
+## Two-Color Foundation
+
+Every directive Mermaid diagram is defined by exactly two colors:
+
+- **`bg`** = `#ffffff` (white background)
+- **`fg`** = `#000000` (black foreground)
+
+All other values are mechanically derived between these two poles. The init directive values below are not arbitrary constants — they are specific points on the bg→fg gradient:
+
+| Element | Value | Derivation |
+|---|---|---|
+| Text (all labels) | `#000000` | fg at 100% |
+| Lines, connectors, signals | `#404040` | fg at ~75% |
+| Primary nodes, note backgrounds | `#909090` | fg at ~56% |
+| Secondary nodes, actor backgrounds | `#808080` | fg at ~50% |
+| Tertiary nodes | `#707070` | fg at ~44% |
+
+To change the palette, change `bg` and `fg` — all values shift consistently. The grayscale-on-white requirement is an instance of this model with `bg=#ffffff` and `fg=#000000`.
+
+## Standards
+
+- ! Include `%%{init:...}%%` theme directive at the start of every Mermaid block
+- ! Use the `base` theme with the standard grayscale init directive derived from the two-color model (not built-in themes)
+- ! For `sequenceDiagram` readability on GitHub/Gist renderers, do not rely on `init.background` or `themeCSS` alone
+- ! For `sequenceDiagram` readability on GitHub/Gist renderers, place participant declarations inside a grey `box ... end` block
+- ! When using `box` in `sequenceDiagram`, place only participant declarations inside the block; message lines and notes must remain outside
+- ! Use black text with grayscale fills for documentation diagrams (bg=white, fg=black)
+- ~ Keep diagrams focused: one concept per diagram
+- ~ Provide a text description or caption alongside every diagram
+- ~ Validate Mermaid rendering fixes with a closed-loop workflow: minimal gist, Playwright render, screenshot inspection
+- ~ Use a minimal reproducer gist before patching large documents
+- ~ Treat renderer quirks as diagram-type-specific; `sequenceDiagram` workarounds SHOULD NOT be generalized to other Mermaid diagram types without testing
+- ≉ Create diagrams with more than 20 nodes in one block; split into focused diagrams
+- ⊗ Rely solely on color to convey meaning (use labels and shapes too)
+- ⊗ Ship low-contrast diagrams (for example, missing init theme or light-on-light text)
+- ⊗ Set individual theme variable values without reference to the two-color derivation table above
+
+## Init Directive (Required)
+
+Prepend to every Mermaid block:
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'primaryColor': '#909090',
+  'secondaryColor': '#808080',
+  'tertiaryColor': '#707070',
+  'primaryTextColor': '#000000',
+  'secondaryTextColor': '#000000',
+  'tertiaryTextColor': '#000000',
+  'lineColor': '#404040',
+  'noteTextColor': '#000000',
+  'noteBkgColor': '#909090',
+  'actorBkg': '#808080',
+  'actorTextColor': '#000000',
+  'actorLineColor': '#404040',
+  'signalColor': '#404040'
+}}}%%
+```
+
+For `stateDiagram-v2`, add these keys to the existing `themeVariables` map
+(do not replace the base variables above):
+
+```text
+  'stateLabelColor': '#000000',
+  'compositeBackground': '#a0a0a0'
+```
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## Patterns
+
+- ~ Use the standard init directive (above) as a copy-paste starting point for every diagram
+- ~ Keep diagrams focused: one concept per diagram, split complex flows into linked sub-diagrams
+- ~ Validate rendering changes with a minimal gist before patching large documents
+
+## Diagram Examples
+
+### Flowchart
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'primaryColor': '#909090',
+  'primaryTextColor': '#000000',
+  'lineColor': '#404040'
+}}}%%
+flowchart TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action A]
+    B -->|No| D[Action B]
+    C --> E[End]
+    D --> E
+```
+
+### Sequence Diagram (GitHub/Gist Safe)
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'primaryTextColor': '#000000',
+  'secondaryTextColor': '#000000',
+  'tertiaryTextColor': '#000000',
+  'noteTextColor': '#000000',
+  'primaryColor': '#909090',
+  'secondaryColor': '#808080',
+  'tertiaryColor': '#707070',
+  'lineColor': '#404040',
+  'actorLineColor': '#404040',
+  'signalColor': '#404040',
+  'actorBkg': '#808080',
+  'actorTextColor': '#000000',
+  'noteBkgColor': '#909090'
+}}}%%
+sequenceDiagram
+    box rgb(192, 192, 192) Participants
+        participant A as Alice
+        participant B as Bob
+    end
+    A->>B: Hello
+    B->>A: Hi back
+    Note over A,B: Example
+```
+
+### State Diagram
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'primaryColor': '#909090',
+  'lineColor': '#404040',
+  'primaryTextColor': '#000000',
+  'stateLabelColor': '#000000',
+  'compositeBackground': '#a0a0a0'
+}}}%%
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Review : submit
+    Review --> Approved : approve
+    Review --> Draft : reject
+    Approved --> [*]
+```