@jetrabbits/agentic 0.3.3 → 0.5.0

package/areas/software/security/workflows/security-scan.md

@@ -60,5 +60,34 @@ quality-gates:
 - **Output:** `finding_report.md`; PR review comments
 - **Done when:** report published; PR status set per findings
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /security-scan"])
+  role_1["developer"]
+  role_2["qa"]
+  role_3["team-lead"]
+  step_1["1. SAST Scan"]
+  step_2["2. Dependency Audit"]
+  step_3["3. Secret Scanning"]
+  step_4["4. Infrastructure Scan"]
+  step_5["5. Synthesize & Report"]
+  exit(["No unaddressed Critical findings + report saved = scan complete."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_1 -. owns .-> step_2
+  role_2 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_3 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 No unaddressed Critical findings + report saved = scan complete.

package/areas/software/security/workflows/threat-model-review.md

@@ -58,5 +58,35 @@ quality-gates:
 - **Output:** `.security/threat-models/threat-model-<feature>.md` — DFD + STRIDE table + mitigations
 - **Done when:** all Required findings have assigned controls; document complete
 
+## Agent Interaction Diagram
+
+<!-- agent-diagram:start -->
+```mermaid
+flowchart TD
+  start(["Start /threat-model-review"])
+  role_1["team-lead"]
+  role_2["developer"]
+  role_3["qa"]
+  step_1["1. Parse Feature"]
+  step_2["2. Data Flow Diagram"]
+  step_3["3. STRIDE Analysis"]
+  step_4["4. Prioritize"]
+  step_5["5. Generate Mitigations"]
+  exit(["Published threat model + Required mitigations assigned = secure implementat..."])
+  start --> step_1
+  step_1 --> step_2
+  step_2 --> step_3
+  step_3 --> step_4
+  step_4 --> step_5
+  step_5 --> exit
+  role_1 -. owns .-> step_1
+  role_2 -. owns .-> step_2
+  role_1 -. owns .-> step_3
+  role_3 -. owns .-> step_3
+  role_1 -. owns .-> step_4
+  role_2 -. owns .-> step_5
+```
+<!-- agent-diagram:end -->
+
 ## Exit
 Published threat model + Required mitigations assigned = secure implementation can proceed.

package/docs/agentic-usage.md

@@ -90,7 +90,16 @@ agentic install \
   --specializations software.general,software.backend
 ```
 
-After install, `agentic` writes `.agentic.json` in the target project. It records copied/generated files and their hashes. A later install rerun updates only manifest-managed files and skips files changed by the user. Generated guidance is written to root `AGENTS.md` for most agents and to `.opencode/AGENTS.md` when OpenCode is selected; multi-target installs that include OpenCode and another agent write both files.
+After install, `agentic` writes `.agentic.json` in the target project. It records copied/generated files and their hashes. A later install rerun updates only manifest-managed files and skips files changed by the user. Generated guidance is always written to root `AGENTS.md`; when OpenCode is selected, `agentic` also writes `.opencode/AGENTS.md`.
+
+When Codex is selected, `agentic` creates or updates the project-local `.codex/config.toml` with Codex memories enabled:
+
+```toml
+[features]
+memories = true
+```
+
+This config file follows the same manifest-managed safeguards as other generated project files.
 
 After the project files are generated, `agentic` starts timestamped operational logging and mirrors install output to a temporary log file such as:
 
@@ -137,6 +146,8 @@ TUI uses `fzf` for interactive selection. If `fzf` is missing, `agentic` can:
 
 `--install-fzf` only affects `self-install`. If auto-install fails, self-install still completes.
 
+The CLI supports the system bash 3.2 shipped with macOS and does not require installing a newer bash.
+
 Manual install examples:
 
 Linux:
@@ -163,7 +174,7 @@ scoop install fzf
 
 ## OpenCode optional plugins
 
-When `opencode` is selected, interactive installs ask whether to enable Telegram notifications and `agent-model-mapper`. The answer is stored globally in:
+When `opencode` is selected, interactive installs ask whether to enable `Telegram Notifications` and `Agent Model Mapping`. These are readable menu labels for the stable internal ids `telegram-notification` and `agent-model-mapper`. The answer is stored globally in:
 
 ```text
 ~/.config/agentic/opencode-plugins.json
@@ -171,6 +182,12 @@ When `opencode` is selected, interactive installs ask whether to enable Telegram
 
 Non-interactive installs create a disabled config when no config exists. Interactive installs ask for Telegram `botToken` and `chatId` when `telegram-notification` is selected. Those credentials are written to the target project `.agentic.json` under `settings.opencode_plugins.telegram`, not to `~/.config/agentic/opencode-plugins.json`. Treat `.agentic.json` as plaintext secret-bearing project config when Telegram is enabled and do not commit it to public repositories. When enabled, `agent-model-mapper` runs during interactive `agentic install`/`agentic tui`, uses `fzf` as a dropdown picker when available, and writes `.opencode/opencode.json` only after a Confirm action. OpenCode startup does not load a mapper runtime plugin or prompt for model mapping.
 
+OpenCode model profiles are stored in `extensions/opencode/profiles` and appear in the same optional OpenCode selection menu as the plugin choices. The built-in choices are `OpenAI Model Profile` and `GitHub Copilot Model Profile`; non-interactive installs can choose them with `AGENTIC_OPENCODE_PROFILE=openai` or `AGENTIC_OPENCODE_PROFILE=githubcopilot`. Users can add local profiles under `$HOME/.config/agentic/opencode/profiles/<profile-id>/opencode.json`; for example, `DT/opencode.json` appears as `DT profile` and `GH/opencode.json` appears as `GH profile`. Profile selection merges agent model mappings into `.opencode/opencode.json`, then MCP configuration is merged afterward.
+
+OpenCode MCP config uses top-level `mcp`, not `mcpServers`. Agentic migrates legacy OpenCode `mcpServers` entries into `mcp` during install. Codex continues to use `.codex/config.toml` with `[mcp_servers.*]` sections.
+
+For selected Kubernetes and Docker MCP integrations, `agentic` performs non-fatal local checks after config generation: `kubectl version` for Kubernetes and `docker mcp --version` for Docker MCP. Failed checks appear as warnings in the final install report with official setup links. Docker MCP server entries are generated under the server name `docker`.
+
 ## Context7
 
 For `opencode`, `codex`, `claude`, `cursor`, `gemini`, `kilocode`, and `antigravity`, interactive installs ask whether to add Context7 MCP configuration. If enabled, a follow-up menu chooses either keyless mode or entering `CONTEXT7_API_KEY`. The selected key is written to all selected target configs for the current project. Most targets use project-level files, while `antigravity` is written to the global user path `~/.gemini/antigravity/mcp_config.json`.

package/docs/catalog.schema.json

@@ -44,7 +44,8 @@
                 "uses_skills",
                 "quality_gates",
                 "examples",
-                "skill_refs"
+                "skill_refs",
+                "workflow_diagram"
               ],
               "properties": {
                 "trigger": {
@@ -104,6 +105,9 @@
                     "type": "string"
                   }
                 },
+                "workflow_diagram": {
+                  "type": "string"
+                },
                 "examples": {
                   "type": "object",
                   "required": [

package/docs/mcp/README.md

@@ -0,0 +1,28 @@
+# Agentic MCP server selection
+
+`agentic tui` includes a dedicated `Select MCP servers to enable:` step after target agent platform selection. The fzf flow supports multi-select with Space or Tab, Enter to confirm, Esc to skip, and a `None / skip` entry for users who do not want MCP configuration generated for the current install.
+
+The MCP menu is driven by the CLI MCP registry rather than hardcoded UI rows. The registry tracks each server's id, display title, description, security level, default disabled state, and generated config block.
+
+Supported registry ids:
+
+| id | Description | Security |
+| --- | --- | --- |
+| `opencode-docs` | OpenCode docs MCP | safe |
+| `playwright` | Browser automation via Playwright MCP | sensitive |
+| `kubernetes` | Kubernetes pods/logs/exec management | dangerous |
+| `youtube-transcript` | YouTube transcript extraction | safe |
+| `docker-mcp` | Docker MCP Gateway | dangerous |
+| `context7` | Fresh library documentation | safe |
+| `mempalace` | Persistent project memory | sensitive |
+| `anydb` | Database access MCP | dangerous |
+
+For non-interactive installs, set `AGENTIC_ENABLE_MCPS` to a comma-separated list of registry ids. Dangerous MCPs require explicit confirmation before config is written. In non-interactive installs, set `AGENTIC_CONFIRM_DANGEROUS_MCP=1` to enable selected dangerous MCPs; otherwise agentic skips them and reports a warning.
+
+OpenCode config generation writes current OpenCode-compatible top-level `mcp` entries, not legacy `mcpServers`. Re-running agentic preserves existing unknown fields, preserves an existing `$schema`, updates only the selected MCP entries, and migrates any existing OpenCode `mcpServers` entries into `mcp` before removing the invalid legacy key.
+
+Codex config generation remains TOML-based and writes `[mcp_servers.<name>]` sections in `.codex/config.toml`.
+
+When `kubernetes` is selected, `agentic` checks whether `kubectl version` succeeds. If it does not, install continues and the final report warns with the official kubectl setup guide: <https://kubernetes.io/docs/tasks/tools/>.
+
+When `docker-mcp` is selected, generated MCP server names use `docker` instead of the older `MCP_DOCKER`. `agentic` checks whether `docker mcp --version` succeeds. If it does not, install continues and the final report warns with Docker setup links: <https://docs.docker.com/get-started/get-docker/> and <https://docs.docker.com/ai/mcp-catalog-and-toolkit/>.

package/docs/opencode_setup.md

@@ -33,7 +33,7 @@ When `agentic` installs the OpenCode extension, it configures optional plugins i
 ~/.config/agentic/opencode-plugins.json
 ```
 
-Telegram notifications and agent model mapping are opt-in. Interactive `agentic install` and `agentic tui` ask for OpenCode plugin selection whenever `opencode` is selected; the answer rewrites this config. During manifest-based upgrade/re-install sync, existing plugin settings are kept so automated refreshes do not open prompts. If the config is absent or a plugin is disabled, the plugin returns no hooks and OpenCode continues without that behavior.
+Telegram notifications and agent model mapping are opt-in. Interactive `agentic install` and `agentic tui` ask for OpenCode plugin selection whenever `opencode` is selected. The menu uses readable labels (`Telegram Notifications` and `Agent Model Mapping`) while keeping the stored internal ids `telegram-notification` and `agent-model-mapper`. The answer rewrites this config. During manifest-based upgrade/re-install sync, existing plugin settings are kept so automated refreshes do not open prompts. If the config is absent or a plugin is disabled, the plugin returns no hooks and OpenCode continues without that behavior.
 
 When `telegram-notification` is selected interactively, `agentic` asks for `botToken` and `chatId` and stores them in the target project's `.agentic.json`:
 
@@ -48,5 +48,25 @@ Non-interactive `agentic install` defaults optional plugins to disabled when no
 
 `agent-model-mapper` reads roles from target `.opencode/agents/*.md` and discovers model names from `~/.config/opencode/opencode.json`, then adds models from active providers in `~/.local/share/opencode/auth.json` using non-deprecated entries in `~/.cache/opencode/models.json`. When enabled, interactive `agentic install`/`agentic tui` prompts for a main and fallback model per role, using `fzf` as a dropdown picker when available, and writes `.opencode/opencode.json` only after a Confirm action. OpenCode startup never opens `fzf` or waits for model input because no mapper runtime plugin is shipped or registered.
 
+Agentic also ships reusable OpenCode model profiles in:
+
+```text
+extensions/opencode/profiles/
+```
+
+The current profiles are `OpenAI Model Profile` (`openai/opencode.json`) and `GitHub Copilot Model Profile` (`githubcopilot/opencode.json`). They appear in the same optional OpenCode selection menu as the plugin choices. Selecting one merges its agent model mapping into `.opencode/opencode.json`; later MCP configuration is merged on top, so profile selection does not block future MCP sections.
+
+Users can add local OpenCode profiles in:
+
+```text
+$HOME/.config/agentic/opencode/profiles/<profile-id>/opencode.json
+```
+
+Local profiles appear below the bundled profiles in the optional OpenCode plugin menu using the label `<profile-id> profile`. For example, `$HOME/.config/agentic/opencode/profiles/DT/opencode.json` appears as `DT profile`, and `$HOME/.config/agentic/opencode/profiles/GH/opencode.json` appears as `GH profile`.
+
+Selecting `none` applies no model profile and does not copy the baseline `extensions/opencode/opencode.json` just for profile selection. If OpenCode MCPs, Telegram notifications, or agent model mapping are selected, `agentic` may still create or update `.opencode/opencode.json` for those explicit options.
+
+For MCP servers, OpenCode uses top-level `mcp` entries. Agentic migrates legacy `mcpServers` in OpenCode configs to `mcp` and removes the invalid key.
+
 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/site/README.md

@@ -17,11 +17,13 @@ For this repo we keep it lightweight and dependency-minimal:
 - site is static HTML/CSS/JS
 - markdown rendering via `marked` CDN
 - full-text search via `lunr` CDN
+- workflow diagrams rendered via `mermaid` CDN
 
 ## Run locally
 
 ```bash
-python3 scripts/build_docs_catalog.py --output docs/site/catalog.json --validate
+make sync-diagrams
+make build
 python3 -m http.server 8000
 # open http://localhost:8000/docs/site/
 ```
@@ -31,7 +33,9 @@ python3 -m http.server 8000
 - Left menu grouped by area.
 - Full-text search by trigger/name/description/examples.
 - Language switcher: EN only / RU only / EN+RU.
+- Light and dark themes, with light as the default and the selected theme saved in the browser.
 - Workflow page with quality gates and source paths.
+- Generated Mermaid agent interaction diagrams for workflows.
 
 
 ## GitHub Pages
@@ -42,3 +46,13 @@ This site can be published from GitHub Pages via Actions workflow (`.github/work
 ## 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.
+
+## Workflow diagrams
+
+Workflow diagrams are generated into `areas/**/workflows/*.md` between `agent-diagram` markers:
+
+```bash
+make sync-diagrams
+```
+
+The catalog builder extracts those Mermaid blocks into `workflow_diagram`, and the static site renders them after Markdown parsing.

package/docs/site/app.js

@@ -2,11 +2,16 @@ let catalog;
 let current = null;
 let idx;
 let docs = [];
+let activeTheme = 'light';
 
 const menuEl = document.getElementById('menu');
 const contentEl = document.getElementById('content');
 const searchEl = document.getElementById('search');
 const langEl = document.getElementById('language');
+const themeToggleEl = document.getElementById('theme-toggle');
+
+applyTheme(getStoredTheme());
+configureMermaid();
 
 init();
 
@@ -91,6 +96,8 @@ ${wf.description || ''}
 ## Roles
 ${(wf.roles || []).map((r) => `<span class="chip">${r}</span>`).join(' ')}
 
+${wf.workflow_diagram ? `## Agent Interaction Diagram\n\n\`\`\`mermaid\n${escapeFence(wf.workflow_diagram)}\n\`\`\`` : ''}
+
 ## Quality gates
 ${(wf.quality_gates || []).map((q) => `- ${q}`).join('\n') || '- —'}
 
@@ -106,12 +113,66 @@ ${examples || '_No examples_'}
 `;
 
   contentEl.innerHTML = marked.parse(md);
+  renderMermaidBlocks();
+}
+
+function getStoredTheme() {
+  try {
+    const theme = window.localStorage.getItem('docs-site-theme');
+    return theme === 'dark' ? 'dark' : 'light';
+  } catch {
+    return 'light';
+  }
+}
+
+function storeTheme(theme) {
+  try {
+    window.localStorage.setItem('docs-site-theme', theme);
+  } catch {
+    // localStorage can be unavailable in private or restricted browser modes.
+  }
+}
+
+function applyTheme(theme) {
+  activeTheme = theme === 'dark' ? 'dark' : 'light';
+  document.documentElement.dataset.theme = activeTheme;
+  if (!themeToggleEl) return;
+  const isDark = activeTheme === 'dark';
+  themeToggleEl.setAttribute('aria-pressed', String(isDark));
+  themeToggleEl.textContent = isDark ? 'Light' : 'Dark';
+}
+
+function configureMermaid() {
+  if (!window.mermaid) return;
+  window.mermaid.initialize({
+    startOnLoad: false,
+    securityLevel: 'strict',
+    theme: activeTheme === 'dark' ? 'dark' : 'default',
+  });
 }
 
 function escapeFence(s) {
   return (s || '').replace(/```/g, '\\\`\\\`\\\`');
 }
 
+async function renderMermaidBlocks() {
+  const blocks = [...contentEl.querySelectorAll('code.language-mermaid')];
+  if (!blocks.length) return;
+
+  const nodes = blocks.map((block) => {
+    const diagram = document.createElement('div');
+    diagram.className = 'mermaid';
+    diagram.textContent = block.textContent;
+    block.parentElement.replaceWith(diagram);
+    return diagram;
+  });
+
+  if (window.mermaid) {
+    configureMermaid();
+    await window.mermaid.run({ nodes });
+  }
+}
+
 searchEl.addEventListener('input', () => {
   const q = searchEl.value.trim();
   if (!q) {
@@ -125,3 +186,10 @@ searchEl.addEventListener('input', () => {
 langEl.addEventListener('change', () => {
   if (current) renderWorkflow(current.id);
 });
+
+themeToggleEl.addEventListener('click', () => {
+  const nextTheme = activeTheme === 'dark' ? 'light' : 'dark';
+  applyTheme(nextTheme);
+  storeTheme(nextTheme);
+  if (current) renderWorkflow(current.id);
+});