@jetrabbits/agentic 0.0.4 → 0.1.0

package/docs/opencode_setup.md

@@ -0,0 +1,48 @@
+# OpenCode setup
+
+## Configuration
+
+The main OpenCode configuration file is located at:
+
+```text
+~/.config/opencode/opencode.json
+```
+
+## Authentication
+
+### Auth files
+
+OpenCode stores authentication data in two locations:
+
+| Path | Description |
+|------|-------------|
+| `~/.config/opencode/` | Plugin-level credentials (for example, `antigravity-accounts.json`) |
+| `~/.local/share/opencode/auth.json` | Primary provider tokens (OpenAI, Google, and others) |
+
+## Notes
+
+- Back up credentials before machine migration.
+- Keep auth files out of version control.
+- Prefer least-privilege API keys for automation.
+
+## Agentic optional plugins
+
+When `agentic` installs the OpenCode extension, it configures optional plugins in:
+
+```text
+~/.config/agentic/opencode-plugins.json
+```
+
+Telegram notifications and model checking are opt-in. If the config is absent or a plugin is disabled, the plugin returns no hooks and OpenCode continues without that behavior.
+
+Telegram notifications use either the stored config values or these environment variables:
+
+```text
+OPENCODE_TELEGRAM_BOT_TOKEN
+OPENCODE_TELEGRAM_CHAT_ID
+```
+
+Non-interactive `agentic install` defaults optional plugins to disabled when no config exists.
+
+For OpenCode targets, `agentic` writes generated operating guidance to `.opencode/AGENTS.md`. If OpenCode is installed
+alongside another agent target, root `AGENTS.md` is generated as well for the non-OpenCode target.

package/docs/prompt-format.md

@@ -0,0 +1,80 @@
+# Prompt format standard (EN/RU)
+
+This repository expects every `areas/**/prompts/*.md` file to follow a strict structure so docs generation can reliably extract examples.
+
+## Required structure
+
+1. YAML front matter:
+
+```md
+---
+workflow: your-workflow-stem
+---
+```
+
+2. Prompt header:
+
+```md
+# Prompt: `/your-workflow-stem`
+```
+
+3. Use-when line:
+
+```md
+Use when: short scenario.
+```
+
+4. Two or three examples:
+
+```md
+## Example 1 — Human-readable title
+
+**EN:**
+```
+/prompt-command
+...
+```
+
+**RU:**
+```
+/prompt-command
+...
+```
+```
+
+## Rules
+
+- `workflow:` in front matter is mandatory and must match a sibling file in `workflows/<workflow>.md`.
+- Prompt filename must match the workflow stem, e.g. `prompts/testing-ci-pipeline.md` for `workflows/testing-ci-pipeline.md`.
+- Prompt header and every slash command inside examples must be canonical and match the workflow stem, e.g. `/testing-ci-pipeline`.
+- `Workflow link command:` is deprecated and must not appear.
+- Every example must include **both** EN and RU fenced code blocks.
+- Every prompt must contain **2 or 3** examples.
+- Keep command and input payload realistic and copy-paste ready.
+- Prefer concise titles for examples.
+- Generic scaffold placeholders such as `<project context>` are not allowed.
+
+## Validation
+
+Run local format checks:
+
+```bash
+python3 scripts/lint_prompts.py
+```
+
+Run full catalog consistency checks:
+
+```bash
+python3 scripts/build_docs_catalog.py --validate
+```
+
+
+## Mapping logic
+
+Catalog builder links prompts to workflows using the prompt front matter key:
+
+```yaml
+workflow: workflow-file-name
+```
+
+Validation then requires prompt filename, header command, and example commands to match that same workflow stem.

package/docs/site/README.md

@@ -0,0 +1,44 @@
+# Markdown docs site (search + menu)
+
+This prototype renders a documentation site directly from markdown-derived catalog data.
+
+## Why this stack
+
+The user requirement was: site from markdown with search and menu. We evaluated popular GitHub projects:
+
+- docsify: https://github.com/docsifyjs/docsify
+- MkDocs: https://github.com/mkdocs/mkdocs
+- Docusaurus: https://github.com/facebook/docusaurus
+- markdown-it (parser): https://github.com/markdown-it/markdown-it
+
+For this repo we keep it lightweight and dependency-minimal:
+
+- catalog is generated offline by Python script from `areas/**/{workflows,prompts}`
+- site is static HTML/CSS/JS
+- markdown rendering via `marked` CDN
+- full-text search via `lunr` CDN
+
+## Run locally
+
+```bash
+python3 scripts/build_docs_catalog.py --output docs/site/catalog.json --validate
+python3 -m http.server 8000
+# open http://localhost:8000/docs/site/
+```
+
+## Features
+
+- Left menu grouped by area.
+- Full-text search by trigger/name/description/examples.
+- Language switcher: EN only / RU only / EN+RU.
+- Workflow page with quality gates and source paths.
+
+
+## GitHub Pages
+
+This site can be published from GitHub Pages via Actions workflow (`.github/workflows/docs-site.yml`).
+
+
+## Workflow mapping
+
+Prompt-to-workflow mapping is command-based: `/workflow-file-name` in prompt text links to `workflows/<workflow-file-name>.md` in the same area.

package/docs/site/app.js

@@ -0,0 +1,127 @@
+let catalog;
+let current = null;
+let idx;
+let docs = [];
+
+const menuEl = document.getElementById('menu');
+const contentEl = document.getElementById('content');
+const searchEl = document.getElementById('search');
+const langEl = document.getElementById('language');
+
+init();
+
+async function init() {
+  const res = await fetch('./catalog.json');
+  catalog = await res.json();
+  buildIndex();
+  renderMenu(catalog.areas);
+  if (docs[0]) renderWorkflow(docs[0].id);
+}
+
+function buildIndex() {
+  docs = [];
+  for (const area of catalog.areas) {
+    for (const wf of area.workflows) {
+      docs.push({
+        id: `${area.area}:${wf.trigger}`,
+        area: area.area,
+        trigger: wf.trigger,
+        name: wf.name,
+        description: wf.description,
+        examples: (wf.examples?.both || []).map((e) => `${e.en}\n${e.ru}`).join('\n'),
+        data: wf,
+      });
+    }
+  }
+
+  idx = lunr(function () {
+    this.ref('id');
+    this.field('area');
+    this.field('trigger');
+    this.field('name');
+    this.field('description');
+    this.field('examples');
+    docs.forEach((d) => this.add(d));
+  });
+}
+
+function renderMenu(areas, filteredIds = null) {
+  menuEl.innerHTML = '';
+  for (const area of areas) {
+    const title = document.createElement('div');
+    title.className = 'area-title';
+    title.textContent = area.area;
+    menuEl.appendChild(title);
+
+    for (const wf of area.workflows) {
+      const id = `${area.area}:${wf.trigger}`;
+      if (filteredIds && !filteredIds.has(id)) continue;
+      const btn = document.createElement('button');
+      btn.className = 'wf-btn';
+      btn.textContent = `${wf.trigger} — ${wf.name}`;
+      btn.onclick = () => renderWorkflow(id);
+      menuEl.appendChild(btn);
+    }
+  }
+}
+
+function renderWorkflow(id) {
+  current = docs.find((d) => d.id === id);
+  if (!current) return;
+  const wf = current.data;
+  const lang = langEl.value;
+
+  const examples = (wf.examples?.both || []).map((ex) => {
+    const blocks = [];
+    if (lang === 'both' || lang === 'en') blocks.push(`**EN**\n\n\
+\`\`\`\n${escapeFence(ex.en)}\n\`\`\``);
+    if (lang === 'both' || lang === 'ru') blocks.push(`**RU**\n\n\
+\`\`\`\n${escapeFence(ex.ru)}\n\`\`\``);
+    return `### Example ${ex.number} — ${ex.title}\n\n${blocks.join('\n\n')}`;
+  }).join('\n\n');
+
+  const md = `
+# ${wf.name}  
+\`${wf.trigger}\`
+
+${wf.description || ''}
+
+**Use when:** ${wf.use_when || '—'}
+
+## Roles
+${(wf.roles || []).map((r) => `<span class="chip">${r}</span>`).join(' ')}
+
+## Quality gates
+${(wf.quality_gates || []).map((q) => `- ${q}`).join('\n') || '- —'}
+
+## Skills
+${(wf.skill_refs || []).map((s) => `- ${s.name} (${s.path || "missing"})`).join('\n') || '- —'}
+
+## Examples (${lang.toUpperCase()})
+${examples || '_No examples_'}
+
+---
+
+<div class="meta">Workflow source: <code>${wf.workflow_path}</code><br/>Prompt source: <code>${wf.prompt_path || '—'}</code></div>
+`;
+
+  contentEl.innerHTML = marked.parse(md);
+}
+
+function escapeFence(s) {
+  return (s || '').replace(/```/g, '\\\`\\\`\\\`');
+}
+
+searchEl.addEventListener('input', () => {
+  const q = searchEl.value.trim();
+  if (!q) {
+    renderMenu(catalog.areas);
+    return;
+  }
+  const results = idx.search(`${q}*`);
+  renderMenu(catalog.areas, new Set(results.map((r) => r.ref)));
+});
+
+langEl.addEventListener('change', () => {
+  if (current) renderWorkflow(current.id);
+});