@venizia/ignis-docs 0.0.5 → 0.0.6-0

package/wiki/references/components/template/errors-page.md

@@ -0,0 +1,100 @@
+# Error Reference Page Template (Tier 2 -- errors.md)
+
+The "fix what's broken" page. A developer reads this when they encounter an error or unexpected behavior. Contains error tables organized by source and troubleshooting entries with cause/fix pairs.
+
+Paired with [Setup](./setup-page), [Usage](./usage-page), and [API Reference](./api-page).
+
+## When to Use
+
+Always created alongside the other 3 pages for Tier 2 components.
+
+## Page Structure
+
+```markdown
+# {Component Name} -- Error Reference
+
+> Error codes, error conditions, and troubleshooting for the [{Component Name}](./) component.
+
+## Error Reference
+
+### {Error Source 1} (e.g., "Component Errors", "JWTTokenService Errors")
+
+| Error / Condition | When It Occurs |
+|-------------------|----------------|
+| `Error message or code` | Trigger condition |
+| `Another error` | Another trigger |
+
+### {Error Source 2}
+
+| Error / Condition | When It Occurs |
+|-------------------|----------------|
+| `Error message or code` | Trigger condition |
+
+### {Error Source 3} (repeat as needed)
+
+| Error / Condition | When It Occurs |
+|-------------------|----------------|
+| `Error message or code` | Trigger condition |
+
+## Troubleshooting
+
+### "{Exact error message or symptom}"
+
+**Cause:** Why this happens.
+
+**Fix:**
+
+` ``typescript
+// Fix example
+` ``
+
+### "{Another common issue}"
+
+**Cause:** Why this happens.
+
+**Fix:** How to resolve it.
+
+### "{Third issue}"
+
+**Cause:** Why this happens.
+
+**Fix:**
+
+` ``typescript
+// Fix example
+` ``
+
+## See Also
+
+- [Setup & Configuration](./) -- Quick reference, setup steps, configuration options
+- [Usage & Examples](./usage) -- Usage patterns, examples, API endpoints
+- [API Reference](./api) -- Architecture, method signatures, internals
+
+- **Guides:**
+  - [Components](/guides/core-concepts/components) - Component system overview
+
+- **Components:**
+  - [All Components](../index) - Built-in components list
+```
+
+## Rules
+
+- **File name:** Always `errors.md` inside the component directory
+- **Focus:** What can go wrong and how to fix it
+- **Error Reference section:** Organize error tables by source class/module (e.g., "Component Errors", "TokenService Errors", "Controller Errors")
+- **Error table columns:** Use `Error / Condition` and `When It Occurs`. Keep descriptions concise
+- **Troubleshooting section:** Minimum 2 entries, maximum 10. Order by frequency -- most common issue first
+- **Troubleshooting heading** uses the exact error message in quotes, or a clear symptom description
+- **Cause** is 1-2 sentences explaining why
+- **Fix** includes a code example when the fix involves code changes
+- **No setup steps** on this page -- those are in `index.md`
+- **No usage examples** on this page -- those are in `usage.md`
+- **No architecture** on this page -- those are in `api.md`
+- **No collapsible sections** -- show all content directly
+- Use `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!IMPORTANT]` callouts
+
+## Where to Find Error Messages
+
+1. Component source: `component.ts` -- look for `throw getError()` and `ApplicationError`
+2. Helper source: the underlying helper's error handling
+3. Common misconfiguration patterns from the binding keys and options

package/wiki/references/components/template/index.md

@@ -0,0 +1,104 @@
+# Component Documentation Template
+
+Guide for writing consistent, professional component reference docs for Ignis.
+
+## Principles
+
+- **Setup-first** -- Get the reader to a working component as fast as possible
+- **Show everything** -- No collapsible sections; use `####` sub-headings for verbose content
+- **Scannable top-level** -- Tables, short code blocks, and callouts for navigation
+- **Earn your section** -- Remove any section that doesn't apply to the component
+
+## Tiers
+
+| Tier | Structure | When to Use | Examples |
+|------|-----------|-------------|----------|
+| **Tier 1** | [Single page](./single-page) | 5 or fewer config options, straightforward behavior | Health Check, Request Tracker, Swagger |
+| **Tier 2** | 4 pages | 6+ config options, multiple strategies/providers, architectural depth | Authentication, Mail, Socket.IO, WebSocket, Static Asset |
+
+### Tier 1 -- Single Page
+
+One file: `{component-slug}.md` (e.g., `health-check.md`). Contains everything: Quick Reference, Setup, Configuration, Binding Keys, Troubleshooting, See Also.
+
+See [Single-Page Template](./single-page).
+
+### Tier 2 -- Four Pages
+
+A directory with 4 files:
+
+| File | Page Title | Content | Template |
+|------|-----------|---------|----------|
+| `index.md` | Setup & Configuration | Quick ref, imports, setup steps 1-2, config tables, binding keys | [Template](./setup-page) |
+| `usage.md` | Usage & Examples | Step 3 usage, patterns, flows, API endpoints, integration examples | [Template](./usage-page) |
+| `api.md` | API Reference | Architecture diagrams, method signatures, internals, types | [Template](./api-page) |
+| `errors.md` | Error Reference | Error tables by source, troubleshooting entries | [Template](./errors-page) |
+
+#### Sidebar Pattern
+
+```typescript
+{
+  text: 'ComponentName',
+  collapsed: true,
+  items: [
+    { text: 'Setup & Configuration', link: '/references/components/slug/' },
+    { text: 'Usage & Examples', link: '/references/components/slug/usage' },
+    { text: 'API Reference', link: '/references/components/slug/api' },
+    { text: 'Error Reference', link: '/references/components/slug/errors' },
+  ],
+},
+```
+
+#### Cross-Links
+
+Every page in a Tier 2 set gets a `## See Also` footer linking to its 3 sibling pages (omit the current page):
+
+```markdown
+## See Also
+
+- [Setup & Configuration](./) -- Quick reference, setup steps, configuration options
+- [Usage & Examples](./usage) -- Usage patterns, examples, API endpoints
+- [API Reference](./api) -- Architecture, method signatures, internals
+- [Error Reference](./errors) -- Error tables and troubleshooting
+```
+
+Add external links (guides, helpers, libraries) after the sibling links.
+
+## Source Paths
+
+When documenting a component, find source material here:
+
+| What | Path |
+|------|------|
+| Binding keys | `packages/core/src/components/{name}/common/keys.ts` |
+| Config types | `packages/core/src/components/{name}/common/types.ts` |
+| Error messages | `packages/core/src/components/{name}/component.ts` -- look for `throw getError()` |
+| Helper source | `packages/helpers/src/helpers/{name}/` |
+
+## Callout Standard
+
+Use **GitHub-style only** -- never `::: tip` or `::: warning`:
+
+```markdown
+> [!NOTE]
+> Informational -- behavior clarification
+
+> [!TIP]
+> Suggestion or best practice
+
+> [!WARNING]
+> Gotcha, deprecation, or security concern
+
+> [!IMPORTANT]
+> Critical functionality impact
+```
+
+## Content Visibility
+
+**All content is always visible** -- no `::: details` collapsible blocks.
+
+Use `####` sub-headings to organize verbose content like:
+- Import Paths
+- Full Options Reference
+- Type definitions
+- API request/response schemas
+- Source code examples

package/wiki/references/components/template/setup-page.md

@@ -0,0 +1,134 @@
+# Setup & Configuration Page Template (Tier 2 -- index.md)
+
+The "get it working" page for complex components. Everything a developer needs on Day 1: what the component is, how to install it, how to configure it, and what binding keys it uses.
+
+Paired with [Usage](./usage-page), [API Reference](./api-page), and [Error Reference](./errors-page).
+
+## When to Use
+
+- Component has 6+ configuration options or multiple config groups
+- Setup involves strategy selection, multiple providers, or multi-step integration
+- There's enough depth to warrant separate Usage, API, and Error pages
+
+## Page Structure
+
+```markdown
+# {Component Name}
+
+{One-line description of what this component does.}
+
+> [!IMPORTANT]
+> {Only if there's a critical runtime/dependency note. Remove entirely if not needed.}
+
+## Quick Reference
+
+| Item | Value |
+|------|-------|
+| **Package** | `@venizia/ignis` |
+| **Class** | `{ComponentClass}` |
+| **Helper** | [`{HelperClass}`](/references/helpers/{slug}) |
+| **Runtimes** | Both / Bun only |
+
+| Sub-component | Purpose |
+|---------------|---------|
+| **ClassA** | What it does |
+| **ClassB** | What it does |
+
+#### Import Paths
+
+` ``typescript
+import { ComponentClass, BindingKeys } from '@venizia/ignis';
+import type { IConfigOptions } from '@venizia/ignis';
+` ``
+
+## Setup
+
+### Step 1: Bind Configuration
+
+Show the minimum viable setup first, then variants.
+
+` ``typescript
+// Minimal setup
+this.bind<IConfigType>({ key: Keys.CONFIG }).toValue({
+  // required fields only
+});
+` ``
+
+> [!TIP]
+> {Optional: point to other setup variants if applicable}
+
+#### Alternative: {Variant Name} Setup
+
+` ``typescript
+// Full variant setup
+` ``
+
+### Step 2: Register Component
+
+` ``typescript
+this.component(ComponentClass);
+` ``
+
+> [!NOTE]
+> Step 3 (using the component) is covered in [Usage & Examples](./usage).
+
+## Configuration
+
+Group options by logical sections when the component has multiple config interfaces.
+
+### {Config Group 1} (`IConfigGroupOptions`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `option` | `string` | `'default'` | What it controls |
+
+#### {IConfigGroupOptions} -- Full Reference
+
+` ``typescript
+interface IConfigGroupOptions {
+  // full interface
+}
+` ``
+
+### {Config Group 2} (`IConfigGroup2Options`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `option` | `string` | `'default'` | What it controls |
+
+## Binding Keys
+
+| Key | Constant | Type | Required | Default |
+|-----|----------|------|----------|---------|
+| `@app/ns/key` | `Keys.CONSTANT` | `Type` | Yes/No | value or `--` |
+
+> [!NOTE]
+> {Any important notes about binding order or conditional requirements}
+
+## See Also
+
+- [Usage & Examples](./usage) -- Usage patterns, examples, API endpoints
+- [API Reference](./api) -- Architecture, method signatures, internals
+- [Error Reference](./errors) -- Error tables and troubleshooting
+
+- **Guides:**
+  - [Components](/guides/core-concepts/components) - Component system overview
+
+- **Components:**
+  - [All Components](../index) - Built-in components list
+```
+
+## Rules
+
+- **File name:** Always `index.md` inside a directory named after the component
+- **Focus:** Getting the developer from zero to configured. Setup, config, keys
+- **Only Steps 1-2** on this page -- Step 3 (usage) goes in `usage.md`
+- **No architecture diagrams** on this page -- those go in `api.md`
+- **No internal lifecycle details** on this page -- those go in `api.md`
+- **No error tables** on this page -- those go in `errors.md`
+- **No troubleshooting** on this page -- those go in `errors.md`
+- **Configuration groups:** When a component has multiple config interfaces, use `###` sub-headings per group
+- **Setup variants:** Show minimal setup at the top level. Put alternative configurations under `####` sub-headings
+- **See Also:** Always link to the 3 sibling pages first, then external links
+- **No collapsible sections** -- show all content directly using `####` sub-headings for verbose content (full interfaces, alternative setups)
+- Use `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!IMPORTANT]` callouts

package/wiki/references/components/template/single-page.md

@@ -0,0 +1,132 @@
+# Single-Page Component Template (Tier 1)
+
+For simple components with few configuration options and straightforward behavior (e.g., Health Check, Request Tracker, Swagger). Everything fits on one page.
+
+## When to Use
+
+- Component has 5 or fewer configuration options
+- No complex architecture worth diagramming
+- Behavior is self-explanatory from setup alone
+
+## Page Structure
+
+```markdown
+# {Component Name}
+
+{One-line description of what this component does.}
+
+> [!IMPORTANT]
+> {Only if there's a critical runtime/dependency note. Remove entirely if not needed.}
+
+## Quick Reference
+
+| Item | Value |
+|------|-------|
+| **Package** | `@venizia/ignis` |
+| **Class** | `{ComponentClass}` |
+| **Helper** | [`{HelperClass}`](/references/helpers/{slug}) |
+| **Runtimes** | Both / Bun only |
+
+#### Import Paths
+
+` ``typescript
+import { ComponentClass, BindingKeys } from '@venizia/ignis';
+import type { IConfigOptions } from '@venizia/ignis';
+` ``
+
+## Setup
+
+### Step 1: Bind Configuration
+
+` ``typescript
+this.bind<IConfigType>({ key: Keys.CONFIG }).toValue({
+  // minimal config here
+});
+` ``
+
+### Step 2: Register Component
+
+` ``typescript
+this.component(ComponentClass);
+` ``
+
+### Step 3: Use
+
+` ``typescript
+// How downstream code interacts with the component
+` ``
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `option` | `string` | `'default'` | What it controls |
+
+#### {IConfigType} -- Full Reference
+
+` ``typescript
+interface IConfigType {
+  // full interface
+}
+` ``
+
+## Binding Keys
+
+| Key | Constant | Type | Required | Default |
+|-----|----------|------|----------|---------|
+| `@app/ns/key` | `Keys.CONSTANT` | `Type` | Yes/No | value or `--` |
+
+## API Endpoints
+
+> Only include if the component exposes REST routes. Remove entirely if not.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/path` | What it returns |
+
+#### Request & Response Schemas
+
+**GET /path**
+
+Response `200`:
+` ``json
+{ "status": "ok" }
+` ``
+
+## Troubleshooting
+
+### "{Exact error message or symptom}"
+
+**Cause:** Why this happens.
+
+**Fix:**
+
+` ``typescript
+// Fix example
+` ``
+
+### "{Another common issue}"
+
+**Cause:** Why this happens.
+
+**Fix:** How to resolve it.
+
+## See Also
+
+- **Guides:**
+  - [Components](/guides/core-concepts/components) - Component system overview
+
+- **Components:**
+  - [All Components](./index) - Built-in components list
+```
+
+## Rules
+
+- **One page, one component.** No sub-pages, no sub-directories.
+- **File name:** `{component-slug}.md` (e.g., `health-check.md`, `swagger.md`)
+- **Quick Reference helper row:** Only include if the component wraps a helper class.
+- **API Endpoints section:** Only include if the component registers REST routes. Remove entirely otherwise.
+- **Troubleshooting:** Minimum 2 entries, maximum 5.
+- **See Also:** Inline at the bottom -- no separate page.
+- **No collapsible sections** -- show all content directly using `####` sub-headings for verbose content (full interfaces, controller source, request/response schemas).
+- Use `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!IMPORTANT]` callouts.

package/wiki/references/components/template/usage-page.md

@@ -0,0 +1,127 @@
+# Usage & Examples Page Template (Tier 2 -- usage.md)
+
+The "use it effectively" page. A developer reads this on Day 2 when they have the component running and need to integrate it into their application. Contains Step 3 from the setup flow, usage patterns, API endpoint specifications, and integration examples.
+
+Paired with [Setup](./setup-page), [API Reference](./api-page), and [Error Reference](./errors-page).
+
+## When to Use
+
+Always created alongside the other 3 pages for Tier 2 components.
+
+## Page Structure
+
+```markdown
+# {Component Name} -- Usage & Examples
+
+> Usage patterns, integration examples, and API specifications for the [{Component Name}](./) component.
+
+## Using the Component
+
+Content from "Step 3" -- how downstream code interacts with what the component provides.
+
+### {Primary Usage Pattern}
+
+` ``typescript
+// Main way to use this component
+` ``
+
+### {Secondary Usage Pattern}
+
+` ``typescript
+// Alternative usage
+` ``
+
+## {Feature Section} (repeat as needed)
+
+Group usage examples by feature when the component has multiple capabilities.
+
+### {Sub-feature}
+
+` ``typescript
+// Feature example
+` ``
+
+> [!TIP]
+> {Best practice or recommendation}
+
+## API Endpoints
+
+> Only include if the component registers REST routes.
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| `POST` | `/path` | Yes/No | What it does |
+| `GET` | `/path` | Yes/No | What it returns |
+
+### POST /path
+
+**Request body:**
+
+` ``json
+{
+  "field": "value"
+}
+` ``
+
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| `field` | `string` | Yes | Min 1, max 255 |
+
+**Response `200`:**
+
+` ``json
+{
+  "result": "value"
+}
+` ``
+
+### GET /path
+
+**Response `200`:**
+
+` ``json
+{
+  "data": []
+}
+` ``
+
+## {Integration Section} (optional)
+
+### Frontend Integration
+
+` ``typescript
+// Client-side integration example
+` ``
+
+### {Advanced Pattern}
+
+` ``typescript
+// Advanced usage pattern
+` ``
+
+## See Also
+
+- [Setup & Configuration](./) -- Quick reference, setup steps, configuration options
+- [API Reference](./api) -- Architecture, method signatures, internals
+- [Error Reference](./errors) -- Error tables and troubleshooting
+
+- **Guides:**
+  - [Components](/guides/core-concepts/components) - Component system overview
+
+- **Components:**
+  - [All Components](../index) - Built-in components list
+```
+
+## Rules
+
+- **File name:** Always `usage.md` inside the component directory
+- **Focus:** How to use the component after setup. Patterns, examples, flows, endpoints
+- **Step 3 content lives here** -- the "Use in Services" part of the setup flow
+- **API Endpoints:** Full request/response specifications go here, not in `api.md`. Show all status codes, all fields, all constraints
+- **No setup steps** on this page -- those are in `index.md`
+- **No architecture diagrams** on this page -- those go in `api.md`
+- **No error tables** on this page -- those go in `errors.md`
+- **Feature grouping:** When a component has multiple features (e.g., template engine, queue executors, verification generators), use `##` sections for each
+- **Code-heavy page** -- every pattern should have a code example
+- **No collapsible sections** -- show all content directly using `####` sub-headings
+- Use `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!IMPORTANT]` callouts