diff --git a/cortex/context_loader.py b/cortex/context_loader.py
index 1a9f0f4..d8b59ba 100644
--- a/cortex/context_loader.py
+++ b/cortex/context_loader.py
@@ -1,5 +1,9 @@
+from pathlib import Path
+
from persona import persona_path
+_STATIC_DIR = Path(__file__).parent / "static"
+
# Core identity files — always loaded regardless of tier
_CORE = ["SOUL.md", "IDENTITY.md"]
@@ -52,8 +56,14 @@ def load_context(
if proto_path.exists():
parts.append(f"--- PROTOCOLS.md ---\n{proto_path.read_text()}")
+ # Global tool reference (same for all personas)
+ tools_path = _STATIC_DIR / "TOOLS.md"
+ if tools_path.exists():
+ parts.append(f"--- TOOLS.md ---\n{tools_path.read_text()}")
+
+ # Persona-specific help additions (optional)
help_path = inara_dir / "HELP.md"
- if help_path.exists():
+ if help_path.exists() and help_path.stat().st_size > 10:
parts.append(f"--- HELP.md ---\n{help_path.read_text()}")
# ── 4. Pending reminders (tier 2+) ────────────────────────────
diff --git a/cortex/static/HELP.md b/cortex/static/HELP.md
index 8e1b365..e649e86 100644
--- a/cortex/static/HELP.md
+++ b/cortex/static/HELP.md
@@ -59,104 +59,7 @@ The orchestrator runs a multi-step tool loop:
The ⚡ toggle is **independent of the Role selector** — you can use any role (chat, coder, research, etc.) with or without tools. The orchestrator model is configured in **Account → Model Registry → Role Assignments → Orchestrator**. By default this is Gemini API.
-**Available tools:**
-
-¹ Admin only — requires the `admin` role. Invisible to regular users.
-² Confirmation required — the orchestrator pauses and shows Confirm / Deny buttons before executing.
-
-**Web**
-
-| Tool | What it does |
-|---|---|
-| `web_search` | DuckDuckGo search — returns titles, URLs, and snippets for the top results |
-| `http_fetch` | Fetch a specific URL and return the response body (8 192 char cap) |
-
-**Files** ¹
-
-| Tool | What it does |
-|---|---|
-| `file_read` ¹ | Read any file under the persona home directory |
-| `file_list` ¹ | List files and directories with sizes (200 entry cap) |
-| `file_write` ¹ ² | Write or append to a file under the persona home directory |
-
-**Shell** ¹
-
-| Tool | What it does |
-|---|---|
-| `shell_exec` ¹ ² | Run any shell command on the Cortex host; timeout 1–120 s |
-| `claude_allow_dir` ¹ | Add a directory to Claude Code's auto-allowed paths |
-
-**System** ¹
-
-| Tool | What it does |
-|---|---|
-| `cortex_restart` ¹ ² | Restart the Cortex service (5 s delay); connection drops — refresh the page |
-| `cortex_logs` ¹ | Recent lines from the systemd journal (default 50, max 200) |
-| `cortex_status` ¹ | Current git branch, commit, ahead/behind remote, and service state |
-| `cortex_update` ¹ ² | `git pull` + syntax check all `.py` files; reports what changed. Does **not** restart automatically — call `cortex_restart` after reviewing |
-
-**Tasks**
-
-| Tool | What it does |
-|---|---|
-| `task_list` | List personal tasks; pass `include_done=true` to include completed |
-| `task_create` | Create a task with title, optional notes and due date |
-| `task_update` | Update any fields on an existing task |
-| `task_complete` | Mark a task as complete |
-
-**Cron**
-
-| Tool | What it does |
-|---|---|
-| `cron_list` | List all scheduled jobs for this persona |
-| `cron_add` | Add a scheduled job — accepts cron syntax or plain-English interval |
-| `cron_remove` ² | Remove a scheduled job by ID |
-| `cron_toggle` | Enable or disable a job without removing it |
-
-**Reminders**
-
-| Tool | What it does |
-|---|---|
-| `reminders_add` | Add a reminder with optional label; surfaced in context at Tier 2+ |
-| `reminders_list` | List all pending reminders, numbered for easy removal |
-| `reminders_remove` | Remove a single reminder by number (call `reminders_list` first) |
-| `reminders_clear` ² | Clear all reminders at once |
-
-**Scratchpad**
-
-| Tool | What it does |
-|---|---|
-| `scratch_read` | Read the current scratchpad |
-| `scratch_write` | Overwrite the scratchpad with new content |
-| `scratch_append` | Append a timestamped section to the scratchpad |
-| `scratch_clear` | Erase the scratchpad |
-
-**Notifications** ¹
-
-| Tool | What it does |
-|---|---|
-| `email_send` ¹ | Send an email via SMTP; recipient must match your `email_allowlist.json` |
-| `nc_talk_send` ¹ | Send a message to a Nextcloud Talk conversation |
-
-**Aether Journals**
-
-| Tool | What it does |
-|---|---|
-| `ae_journal_list` | List all journals for the configured AE account (returns names + IDs) |
-| `ae_journal_search` | Search entries by keyword, tag, date range, type, status, or priority |
-| `ae_journal_entries_list` | Browse all entries in a specific journal, newest first; paginated |
-| `ae_journal_entry_read` | Read the full content of a single entry by ID |
-| `ae_journal_entry_create` | Create a new entry with title, content, tags, and summary |
-| `ae_journal_entry_update` | Patch any fields on an existing entry (title, content, tags, summary, enable) |
-| `ae_journal_entry_disable` | Soft-delete an entry (`enable=false`) without permanently removing it |
-| `ae_journal_entry_append` | Append a timestamped section to the bottom of an entry's content |
-| `ae_journal_entry_prepend` | Prepend a timestamped section to the top of an entry's content |
-
-**Aether Tasks** ¹
-
-| Tool | What it does |
-|---|---|
-| `ae_task_list` ¹ | List tasks from the agents_sync Kanban board (admin only) |
+The full tool reference is in the **Tools** tab. 30 tools across web, files, shell, system, tasks, cron, reminders, scratchpad, notifications, and Aether Journals.
Tools mode is best for tasks requiring research, multi-step reasoning, or side effects (e.g. "search for X", "add a task", "what's on my list?", "append this to my journal"). Regular chat is faster for conversational turns.
diff --git a/cortex/static/TOOLS.md b/cortex/static/TOOLS.md
new file mode 100644
index 0000000..7c4c29b
--- /dev/null
+++ b/cortex/static/TOOLS.md
@@ -0,0 +1,103 @@
+# Tool Reference
+
+> This reference covers all 30 orchestrator tools available when the ⚡ toggle is on.
+> Tools are invoked automatically by the orchestrator — you don't call them directly.
+
+¹ **Admin only** — requires the `admin` role. Invisible to regular users.
+² **Confirmation required** — the orchestrator pauses and shows **Confirm / Deny** buttons before executing.
+
+---
+
+## Web
+
+| Tool | What it does |
+|---|---|
+| `web_search` | DuckDuckGo search — returns titles, URLs, and snippets for the top results |
+| `http_fetch` | Fetch a specific URL and return the response body (8 192 char cap) |
+
+## Files ¹
+
+| Tool | What it does |
+|---|---|
+| `file_read` ¹ | Read any file under the persona home directory |
+| `file_list` ¹ | List files and directories with sizes (200 entry cap) |
+| `file_write` ¹ ² | Write or append to a file under the persona home directory |
+
+## Shell ¹
+
+| Tool | What it does |
+|---|---|
+| `shell_exec` ¹ ² | Run any shell command on the Cortex host; timeout 1–120 s |
+| `claude_allow_dir` ¹ | Add a directory to Claude Code's auto-allowed paths |
+
+## System ¹
+
+| Tool | What it does |
+|---|---|
+| `cortex_restart` ¹ ² | Restart the Cortex service (5 s delay); connection drops — refresh the page |
+| `cortex_logs` ¹ | Recent lines from the systemd journal (default 50, max 200) |
+| `cortex_status` ¹ | Current git branch, commit, ahead/behind remote, and service state |
+| `cortex_update` ¹ ² | `git pull` + syntax check all `.py` files; reports what changed. Does **not** restart automatically — call `cortex_restart` after reviewing |
+
+## Tasks
+
+| Tool | What it does |
+|---|---|
+| `task_list` | List personal tasks; pass `include_done=true` to include completed |
+| `task_create` | Create a task with title, optional notes and due date |
+| `task_update` | Update any fields on an existing task |
+| `task_complete` | Mark a task as complete |
+
+## Cron
+
+| Tool | What it does |
+|---|---|
+| `cron_list` | List all scheduled jobs for this persona |
+| `cron_add` | Add a scheduled job — accepts cron syntax or plain-English interval |
+| `cron_remove` ² | Remove a scheduled job by ID |
+| `cron_toggle` | Enable or disable a job without removing it |
+
+## Reminders
+
+| Tool | What it does |
+|---|---|
+| `reminders_add` | Add a reminder with optional label; surfaced in context at Tier 2+ |
+| `reminders_list` | List all pending reminders, numbered for easy removal |
+| `reminders_remove` | Remove a single reminder by number (call `reminders_list` first) |
+| `reminders_clear` ² | Clear all reminders at once |
+
+## Scratchpad
+
+| Tool | What it does |
+|---|---|
+| `scratch_read` | Read the current scratchpad |
+| `scratch_write` | Overwrite the scratchpad with new content |
+| `scratch_append` | Append a timestamped section to the scratchpad |
+| `scratch_clear` | Erase the scratchpad |
+
+## Notifications ¹
+
+| Tool | What it does |
+|---|---|
+| `email_send` ¹ | Send an email via SMTP; recipient must match your `email_allowlist.json` |
+| `nc_talk_send` ¹ | Send a message to a Nextcloud Talk conversation |
+
+## Aether Journals
+
+| Tool | What it does |
+|---|---|
+| `ae_journal_list` | List all journals for the configured AE account (returns names + IDs) |
+| `ae_journal_search` | Search entries by keyword, tag, date range, type, status, or priority |
+| `ae_journal_entries_list` | Browse all entries in a specific journal, newest first; paginated |
+| `ae_journal_entry_read` | Read the full content of a single entry by ID |
+| `ae_journal_entry_create` | Create a new entry with title, content, tags, and summary |
+| `ae_journal_entry_update` | Patch any fields on an existing entry (title, content, tags, summary, enable) |
+| `ae_journal_entry_disable` | Soft-delete an entry (`enable=false`) without permanently removing it |
+| `ae_journal_entry_append` | Append a timestamped section to the bottom of an entry's content |
+| `ae_journal_entry_prepend` | Prepend a timestamped section to the top of an entry's content |
+
+## Aether Tasks ¹
+
+| Tool | What it does |
+|---|---|
+| `ae_task_list` ¹ | List tasks from the agents_sync Kanban board |
diff --git a/cortex/static/help.html b/cortex/static/help.html
index e608fd6..e9f4394 100644
--- a/cortex/static/help.html
+++ b/cortex/static/help.html
@@ -16,6 +16,7 @@
--pg-text: #e2e8f0; --pg-muted: #94a3b8;
--pg-dim: #64748b; --pg-dimmer: #475569;
--pg-bright: #cbd5e1; --pg-nav-hover: rgba(255,255,255,0.05);
+ --pg-accent: #a78bfa;
}
[data-theme="light"] {
--pg-bg: #f4f2fa; --pg-surface: #ffffff;
@@ -23,6 +24,7 @@
--pg-text: #1a1228; --pg-muted: #5a5478;
--pg-dim: #7a7290; --pg-dimmer: #9e98b0;
--pg-bright: #1a1228; --pg-nav-hover: rgba(0,0,0,0.05);
+ --pg-accent: #7c3aed;
}
*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
@@ -38,110 +40,97 @@
padding: 2rem 1.5rem;
}
- .page {
- max-width: 720px;
- margin: 0 auto;
- }
+ .page { max-width: 720px; margin: 0 auto; }
+ /* ── Page nav ── */
.page-nav {
- display: flex;
- align-items: center;
- gap: 0.25rem;
- margin-bottom: 1.75rem;
- flex-wrap: wrap;
+ display: flex; align-items: center; gap: 0.25rem;
+ margin-bottom: 1.75rem; flex-wrap: wrap;
}
.nav-link {
- display: inline-flex;
- align-items: center;
- padding: 0.3rem 0.6rem;
- border-radius: 6px;
- font-size: 0.8rem;
- font-weight: 500;
- color: var(--pg-dim);
- text-decoration: none;
- transition: color 0.15s, background 0.15s;
- white-space: nowrap;
+ display: inline-flex; align-items: center;
+ padding: 0.3rem 0.6rem; border-radius: 6px;
+ font-size: 0.8rem; font-weight: 500; color: var(--pg-dim);
+ text-decoration: none; transition: color 0.15s, background 0.15s; white-space: nowrap;
}
.nav-link:hover { color: var(--pg-bright); background: var(--pg-nav-hover); }
- .nav-link.active { color: #a78bfa; }
+ .nav-link.active { color: var(--pg-accent); }
.nav-spacer { flex: 1; min-width: 0.5rem; }
.nav-link.nav-logout { color: var(--pg-dimmer); }
.nav-link.nav-logout:hover { color: var(--pg-muted); background: none; }
- header {
- margin-bottom: 2rem;
- padding-bottom: 1rem;
- border-bottom: 1px solid var(--pg-border);
- }
- header h1 { font-size: 1.5rem; font-weight: 700; color: #a78bfa; }
+ /* ── Header ── */
+ header { margin-bottom: 1.5rem; padding-bottom: 1rem; border-bottom: 1px solid var(--pg-border); }
+ header h1 { font-size: 1.5rem; font-weight: 700; color: var(--pg-accent); }
header p { font-size: 0.85rem; color: var(--pg-muted); margin-top: 0.25rem; }
- #help-body { line-height: 1.7; }
+ /* ── Tabs ── */
+ .tab-bar {
+ display: flex; gap: 0.25rem;
+ margin-bottom: 1.25rem;
+ border-bottom: 1px solid var(--pg-border);
+ padding-bottom: 0;
+ }
+ .tab-btn {
+ padding: 0.45rem 1rem;
+ font-size: 0.85rem; font-weight: 500;
+ color: var(--pg-dim);
+ background: none; border: none; border-bottom: 2px solid transparent;
+ cursor: pointer; transition: color 0.15s, border-color 0.15s;
+ margin-bottom: -1px;
+ }
+ .tab-btn:hover { color: var(--pg-bright); }
+ .tab-btn.active { color: var(--pg-accent); border-bottom-color: var(--pg-accent); }
+
+ .tab-panel { display: none; }
+ .tab-panel.active { display: block; }
+
+ /* ── Content ── */
+ .help-body { line-height: 1.7; }
- /* Collapsible sections */
details {
margin-bottom: 0.75rem;
background: var(--pg-surface);
border: 1px solid var(--pg-border);
- border-radius: 8px;
- overflow: hidden;
+ border-radius: 8px; overflow: hidden;
}
summary {
- padding: 0.85rem 1rem;
- font-weight: 600;
- font-size: 0.95rem;
- color: var(--pg-bright);
- cursor: pointer;
- list-style: none;
- display: flex;
- align-items: center;
- gap: 0.5rem;
+ padding: 0.85rem 1rem; font-weight: 600; font-size: 0.95rem;
+ color: var(--pg-bright); cursor: pointer; list-style: none;
+ display: flex; align-items: center; gap: 0.5rem;
}
summary::before {
- content: '▶';
- font-size: 0.65rem;
- color: var(--pg-muted);
+ content: '▶'; font-size: 0.65rem; color: var(--pg-muted);
transition: transform 0.15s;
}
details[open] summary::before { transform: rotate(90deg); }
summary::-webkit-details-marker { display: none; }
+ details > *:not(summary) { padding: 0 1rem 1rem; }
- details > *:not(summary) {
- padding: 0 1rem 1rem;
+ .help-body p { margin: 0.5rem 0; font-size: 0.9rem; color: var(--pg-bright); }
+ .help-body ul { margin: 0.5rem 0 0.5rem 1.25rem; }
+ .help-body li { font-size: 0.9rem; color: var(--pg-bright); margin-bottom: 0.25rem; }
+ .help-body strong { color: var(--pg-text); }
+ .help-body code {
+ background: var(--pg-bg); border: 1px solid var(--pg-border);
+ border-radius: 4px; padding: 0.1em 0.4em;
+ font-size: 0.85em; color: var(--pg-accent);
}
-
- #help-body p { margin: 0.5rem 0; font-size: 0.9rem; color: var(--pg-bright); }
- #help-body ul { margin: 0.5rem 0 0.5rem 1.25rem; }
- #help-body li { font-size: 0.9rem; color: var(--pg-bright); margin-bottom: 0.25rem; }
- #help-body strong { color: var(--pg-text); }
- #help-body code {
- background: var(--pg-bg);
- border: 1px solid var(--pg-border);
- border-radius: 4px;
- padding: 0.1em 0.4em;
- font-size: 0.85em;
- color: #a78bfa;
+ .help-body a { color: var(--pg-accent); }
+ .help-body h1 { font-size: 1.1rem; font-weight: 700; color: var(--pg-text); margin: 0.75rem 0 0.5rem; }
+ .help-body h3 {
+ font-size: 0.8rem; font-weight: 600; color: var(--pg-muted);
+ text-transform: uppercase; letter-spacing: 0.05em; margin: 0.75rem 0 0.25rem;
}
- #help-body a { color: #a78bfa; }
+ .help-body table { width: 100%; border-collapse: collapse; font-size: 0.88rem; margin: 0.5rem 0 0.75rem; }
+ .help-body th, .help-body td { padding: 0.45rem 0.7rem; text-align: left; border-bottom: 1px solid var(--pg-border); }
+ .help-body th { color: var(--pg-muted); font-weight: 600; font-size: 0.8rem; text-transform: uppercase; letter-spacing: 0.04em; }
+ .help-body td { color: var(--pg-bright); }
+ .help-body pre { background: var(--pg-bg); border: 1px solid var(--pg-border); border-radius: 6px; padding: 0.75rem 1rem; overflow-x: auto; margin: 0.5rem 0; }
+ .help-body pre code { background: none; border: none; padding: 0; font-size: 0.85em; color: var(--pg-muted); }
+ .help-body hr { border: none; border-top: 1px solid var(--pg-border); margin: 0.5rem 0; }
- #help-body h3 {
- font-size: 0.8rem;
- font-weight: 600;
- color: var(--pg-muted);
- text-transform: uppercase;
- letter-spacing: 0.05em;
- margin: 0.75rem 0 0.25rem;
- }
-
- #loading { color: var(--pg-muted); font-size: 0.9rem; padding: 1rem 0; }
-
- #help-body table { width: 100%; border-collapse: collapse; font-size: 0.88rem; margin: 0.5rem 0 0.75rem; }
- #help-body th, #help-body td { padding: 0.45rem 0.7rem; text-align: left; border-bottom: 1px solid var(--pg-border); }
- #help-body th { color: var(--pg-muted); font-weight: 600; font-size: 0.8rem; text-transform: uppercase; letter-spacing: 0.04em; }
- #help-body td { color: var(--pg-bright); }
- #help-body pre { background: var(--pg-bg); border: 1px solid var(--pg-border); border-radius: 6px; padding: 0.75rem 1rem; overflow-x: auto; margin: 0.5rem 0; }
- #help-body pre code { background: none; border: none; padding: 0; font-size: 0.85em; color: var(--pg-muted); }
- #help-body hr { border: none; border-top: 1px solid var(--pg-border); margin: 0.5rem 0; }
+ .empty-state { color: var(--pg-dim); font-size: 0.9rem; padding: 2rem 0; text-align: center; }
@@ -159,7 +148,15 @@
-
+
+
+
+
+
+
+
+
+