Initial Commit

.claude/templates/README.md

@@ -0,0 +1,126 @@
+# README-generation templates
+
+This directory holds `@suaveplan/templates` engine templates for auto-generating
+`README.md` files at three levels of the `packages/` tree.
+
+| Template | Target path | Purpose |
+|----------|-------------|---------|
+| `package-readme.template.md` | `packages/<category>/<plugin>/<pkg>/README.md` | Stand-alone npm-package readme |
+| `plugin-readme.template.md` | `packages/<category>/<plugin>/README.md` | Index of packages inside one plugin |
+| `category-readme.template.md` | `packages/<category>/README.md` | Index of all packages in a category |
+
+## How to render
+
+Load the template file as a string, build a context object, and pass both to
+`TemplateEngine` with the **loop-aware preset**:
+
+```ts
+import {
+  TemplateEngine,
+  fullPresetWithLoops,
+} from "@suaveplan/templates";
+import type { ParseState } from "@suaveplan/templates";
+
+const engine = new TemplateEngine();
+engine.usePreset(
+  fullPresetWithLoops(
+    (tpl, ctx, state) =>
+      (engine as unknown as { parseInternal: Function }).parseInternal(
+        tpl,
+        ctx,
+        state
+      )
+  )
+);
+
+const template = await Bun.file(
+  ".claude/templates/package-readme.template.md"
+).text();
+
+const context = {
+  packageName: "@suaveplan/api-plugin-vault",
+  shortDescription: "Per-user vault HTTP plugin for `@suaveplan/api`.",
+  summary: "Per-user vault HTTP plugin...",
+  installCommand: "bun add @suaveplan/api-plugin-vault",
+  quickStartCode: `import { createVaultPlugin } from "@suaveplan/api-plugin-vault";`,
+  quickStartDescription: "After `registry.start()`, the vault plugin...",
+  features: [
+    "Persists `site` records under SurrealDB...",
+    "Enforces per-organization and per-site caps...",
+  ],
+  modules: [
+    { name: "error-codes/error-codes", path: "./src/error-codes/error-codes.md", description: "9 stable `VAULT_PLUGIN_*` codes." },
+    { name: "plugin/plugin", path: "./src/plugin/plugin.md", description: "`createVaultPlugin` factory." },
+  ],
+  otelInstruments: [
+    { type: "Counter", name: "webhook_plugin.deliveries_total", labels: "{event,status,endpoint_id}" },
+  ],
+  otelStatusValues: "`delivered`, `exhausted`, `not_found`",
+  license: "MIT",
+};
+
+const readme = engine.parse(template, context);
+```
+
+## Context shapes
+
+### `package-readme.template.md`
+
+| Key | Type | Required | Notes |
+|-----|------|----------|-------|
+| `packageName` | `string` | ✅ | Full scoped name, e.g. `@suaveplan/templates` |
+| `shortDescription` | `string` | ✅ | ≤120 characters; appended to H1 |
+| `summary` | `string` | ✅ | Multi-line paragraph(s) |
+| `installCommand` | `string` | ✅ | Shell command, e.g. `bun add @suaveplan/templates` |
+| `quickStartCode` | `string` | ✅ | Code inside the `ts` fence (no backticks) |
+| `quickStartDescription` | `string` | ❌ | Paragraph after the quick-start block |
+| `features` | `string[]` | ❌ | Renders the "What it does" section |
+| `modules` | `{name,path,description}[]` | ✅ | Module index bullets |
+| `otelInstruments` | `{type,name,labels?}[]` | ❌ | Renders the "OpenTelemetry" section |
+| `otelStatusValues` | `string` | ❌ | Sentence fragment after the instrument list |
+| `license` | `string` | ✅ | e.g. `MIT` |
+
+### `plugin-readme.template.md`
+
+| Key | Type | Required |
+|-----|------|----------|
+| `pluginName` | `string` | ✅ |
+| `pluginDescription` | `string` | ✅ |
+| `packages` | `{name,path,description}[]` | ✅ |
+
+### `category-readme.template.md`
+
+| Key | Type | Required |
+|-----|------|----------|
+| `categoryName` | `string` | ✅ |
+| `categoryDescription` | `string` | ✅ |
+| `packages` | `{name,path,description}[]` | ✅ |
+
+## Brace-escaping caveat
+
+The `@suaveplan/templates` engine scans the **entire** template (including text
+inside code blocks) for `{identifier}` tokens. If a context string contains a
+literal brace pair that looks like a variable — e.g. `GET /sites/{id}/public` —
+the engine will try to resolve it and, when the identifier is absent from
+context, replace it with an empty string.
+
+When building context objects, avoid bare `{foo}` patterns. Safe work-arounds:
+
+1. **Add a space** — `{ id }` does not match any plugin regex.
+2. **Back-tick wrapping** — `` `{id}` `` is still scanned, but if the value is
+   not in context the engine replaces it with `""`. Only use this when the
+   loss of the braces is acceptable.
+3. **Post-process** — after rendering, run a regex replace that restores any
+   sentinels you placed in the context strings (e.g. `«LBRACE»` → `{`).
+
+Because the package-level readme is aimed at npm consumers with no knowledge of
+the monorepo, the generated text should already avoid monorepo-specific tags
+(`genesis`, migration phases, universal tiers, etc.). The AI generating the
+context object is responsible for stripping that content before rendering.
+
+## Conditional nesting
+
+The `@suaveplan/templates` conditional plugin (`{if:…}…{/if}`) does not support
+nesting. The package template keeps all conditionals at the top level so they
+never wrap each other. Loop bodies may contain inner conditionals safely because
+the loop plugin resolves them recursively before the outer conditional runs.

.claude/templates/category-readme.template.md

@@ -0,0 +1,8 @@
+# {categoryName}
+
+{categoryDescription}
+
+## Packages
+
+{each:packages:pkg}- [`{pkg.name}`]({pkg.path}) — {pkg.description}
+{/each}

.claude/templates/module-docs.md

@@ -0,0 +1,237 @@
+# [Module Name]
+
+## Purpose
+
+Brief description of what this module does and why it exists. Explain the problem it solves and the value it provides.
+
+## Features
+
+- Feature 1 - Brief description
+- Feature 2 - Brief description
+- Feature 3 - Brief description
+- Additional features as needed
+
+## Architecture
+
+High-level architecture explanation
+
+- Design patterns used (e.g., Factory, Singleton, Observer)
+- Key abstractions and interfaces
+- How components interact
+- Performance considerations
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { MyClass } from '@suaveplan/package';
+
+// Basic usage example
+const instance = new MyClass();
+instance.doSomething();
+```
+
+### Advanced Example
+
+```typescript
+import { MyClass, type MyOptions } from '@suaveplan/package';
+
+// More complex usage patterns
+const options: MyOptions = {
+  // Configuration options
+};
+
+const instance = new MyClass(options);
+
+// Advanced usage with callbacks, generics, etc.
+instance.advancedMethod((result) => {
+  console.log('Result:', result);
+});
+```
+
+### Integration Example
+
+```typescript
+// Example showing how this module integrates with other modules
+import { MyClass } from '@suaveplan/package';
+import { RelatedClass } from '@suaveplan/related-package';
+
+const myInstance = new MyClass();
+const relatedInstance = new RelatedClass(myInstance);
+```
+
+## API Reference
+
+### ClassName
+
+Main class description and purpose.
+
+#### constructor(options?: Options)
+
+**`Parameters:`**
+
+- `options` (optional) - Configuration object
+  - `option1: string` - Description of option1
+  - `option2: number` - Description of option2
+  - `option3?: boolean` - Description of optional option3
+
+**Returns:** Instance of ClassName
+
+**`Example:`**
+
+```typescript
+const instance = new ClassName({
+  option1: 'value',
+  option2: 42
+});
+```
+
+#### method(param: Type): ReturnType
+
+Description of what the method does.
+
+**`Parameters:`**
+
+- `param: Type` - Description of the parameter
+  - Include constraints or validation rules
+  - Mention default values if applicable
+
+**Returns:** Description of the return value
+
+**`Throws:`**
+
+- `ErrorType` - When this error occurs
+
+**`Example:`**
+
+```typescript
+const result = instance.method('value');
+```
+
+#### asyncMethod(param: Type): Promise<ReturnType>
+
+Description of what the async method does.
+
+**`Parameters:`**
+
+- `param: Type` - Description
+
+**Returns:** Promise that resolves to description
+
+**`Example:`**
+
+```typescript
+const result = await instance.asyncMethod('value');
+```
+
+### InterfaceName
+
+Description of the interface and when to implement it.
+
+```typescript
+interface InterfaceName {
+  property: Type;
+  method(param: Type): ReturnType;
+}
+```
+
+**`Properties:`**
+
+- `property: Type` - Description of the property
+
+**`Methods:`**
+
+- `method(param: Type): ReturnType` - Description of the method
+
+### TypeName
+
+Description of the type and its use cases.
+
+```typescript
+type TypeName = /* type definition */;
+```
+
+**`Usage:`**
+
+```typescript
+const example: TypeName = /* example value */;
+```
+
+## Implementation Notes
+
+### Design Decisions
+
+- **Decision 1**: Explanation of why this approach was chosen
+  - Alternatives considered
+  - Trade-offs made
+
+- **Decision 2**: Another important design decision
+  - Technical rationale
+  - Impact on performance or maintainability
+
+### Performance Considerations
+
+- **Time Complexity**: O(n) for operation X
+- **Space Complexity**: O(1) for operation Y
+- **Optimizations**: Specific optimizations implemented (caching, memoization, etc.)
+- **Benchmarks**: Performance metrics if available
+
+### Known Limitations
+
+- **Limitation 1**: Description and potential workarounds
+- **Limitation 2**: Description and potential workarounds
+- **Browser Compatibility**: Any browser-specific limitations
+- **Platform Support**: Node.js, Deno, Browser support notes
+
+### Testing Strategy
+
+- Unit tests cover: X, Y, Z
+- Integration tests cover: A, B, C
+- E2E tests cover: P, Q, R
+- Test coverage: XX%
+
+### Migration Guide (if applicable)
+
+If this replaces or significantly changes an existing module
+
+```typescript
+// Old way (deprecated)
+import { OldClass } from '@suaveplan/package';
+const old = new OldClass();
+
+// New way (recommended)
+import { NewClass } from '@suaveplan/package';
+const updated = new NewClass();
+```
+
+## See Also
+
+- [Related Module 1](../related-module/related-module.md) - Brief description of relationship
+- [Related Module 2](../../other-package/module/module.md) - Brief description of relationship
+- [External Documentation](https://example.com/docs) - Relevant external resources
+- [RFC/ADR](../../docs/adr/001-decision.md) - Architecture decision records if applicable
+
+## Changelog
+
+### Version X.Y.Z (YYYY-MM-DD)
+
+- **Added**: New features
+- **Changed**: Changes to existing features
+- **Deprecated**: Soon-to-be removed features
+- **Removed**: Removed features
+- **Fixed**: Bug fixes
+- **Security**: Security improvements
+
+## Contributing
+
+Guidelines specific to this module
+
+- Code style preferences
+- Testing requirements (maintain XX% coverage)
+- Documentation requirements
+- Review process
+
+## License
+
+Indicate if different from project license, otherwise remove this section.

.claude/templates/package-readme.template.md

@@ -0,0 +1,37 @@
+# {packageName} - {shortDescription}
+
+## Summary
+
+{summary}
+
+## Install
+
+```bash
+{installCommand}
+```
+
+## Quick start
+
+```ts
+{quickStartCode}
+```
+
+{quickStartDescription}
+
+{if:features}## What it does
+
+{each:features:feature}- {feature}
+{/each}
+{/if}{if:modules}## Modules
+
+{each:modules:mod}- [`{mod.name}`]({mod.path}) — {mod.description}
+{/each}
+{/if}{if:otelInstruments}## OpenTelemetry
+
+{each:otelInstruments:inst}- {inst.type} `{inst.name}{if:inst.labels}{inst.labels}{/if}`
+{/each}
+{/if}{if:otelStatusValues}Status label values: {otelStatusValues}.
+{/if}
+## License
+
+{license}

.claude/templates/plugin-readme.template.md

@@ -0,0 +1,8 @@
+# {pluginName}
+
+{pluginDescription}
+
+## Packages
+
+{each:packages:pkg}- [`{pkg.name}`]({pkg.path}) — {pkg.description}
+{/each}