personal memory agent
1# solstone App Development Guide
2
3**Complete guide for building apps in the `apps/` directory.**
4
5Apps are the primary way to extend solstone's web interface (Convey). Each app is a self-contained module discovered automatically using **convention over configuration**—no base classes or manual registration required.
6
7> **How to use this document:** This guide serves as a catalog of patterns and references. Each section points to authoritative source files—read those files alongside this guide for complete details. When in doubt, the source code is the definitive reference.
8
9---
10
11## Quick Start
12
13Create a minimal app in two steps:
14
15```bash
16# 1. Create app directory (use underscores, not hyphens!)
17mkdir apps/my_app
18
19# 2. Create workspace template
20touch apps/my_app/workspace.html
21```
22
23**Minimal `workspace.html`:**
24```html
25<h1>Hello from My App!</h1>
26```
27
28**That's it!** Restart Convey and your app is automatically available at `/app/my_app`.
29
30All apps are served via a shared route handler at `/app/{app_name}`. You only need `routes.py` if your app requires custom routes beyond the index page (e.g., API endpoints, form handlers, or navigation routes).
31
32---
33
34## Directory Structure
35
36```
37apps/my_app/
38├── workspace.html # Required: Main content template
39├── routes.py # Optional: Flask blueprint (only if custom routes needed)
40├── tools.py # Optional: App tool functions for agent workflows
41├── call.py # Optional: CLI commands via Typer (auto-discovered)
42├── events.py # Optional: Server-side event handlers (auto-discovered)
43├── app.json # Optional: Metadata (icon, label, facet support)
44├── app_bar.html # Optional: Bottom bar controls (forms, buttons)
45├── background.html # Optional: Background JavaScript service
46├── talent/ # Optional: Custom agents, generators, and skills (auto-discovered)
47│ └── my-skill/ # Optional: Agent Skill directories (SKILL.md + resources)
48├── maint/ # Optional: One-time maintenance tasks (auto-discovered)
49└── tests/ # Optional: App-specific tests (run via make test-apps)
50```
51
52### File Purposes
53
54| File | Required | Purpose |
55|------|----------|---------|
56| `workspace.html` | **Yes** | Main app content (rendered in container) |
57| `routes.py` | No | Flask blueprint for custom routes (API endpoints, forms, etc.) |
58| `tools.py` | No | Callable tool functions for AI agent workflows |
59| `call.py` | No | CLI commands via Typer, accessed as `sol call <app>` (auto-discovered) |
60| `events.py` | No | Server-side Callosum event handlers (auto-discovered) |
61| `app.json` | No | Icon, label, facet support overrides |
62| `app_bar.html` | No | Bottom fixed bar for app controls |
63| `background.html` | No | Background service (WebSocket listeners) |
64| `talent/` | No | Custom agents, generators, and skills (`.md` files + skill subdirectories) |
65| `maint/` | No | One-time maintenance tasks (run on Convey startup) |
66| `tests/` | No | App-specific tests with self-contained fixtures |
67
68---
69
70## Naming Conventions
71
72**Critical for auto-discovery:**
73
741. **App directory**: Use `snake_case` (e.g., `my_app`, **not** `my-app`)
752. **Blueprint variable** (if using routes.py): Must be `{app_name}_bp` (e.g., `my_app_bp`)
763. **Blueprint name** (if using routes.py): Must be `app:{app_name}` (e.g., `"app:my_app"`)
774. **URL prefix**: Convention is `/app/{app_name}` (e.g., `/app/my_app`)
78
79**Index route**: All apps are automatically served at `/app/{app_name}` via a shared handler. You don't need to define an index route in `routes.py`.
80
81See `apps/__init__.py` for discovery logic and route injection.
82
83---
84
85## Required Files
86
87### 1. `workspace.html` - Main Content
88
89The workspace template is included inside the app container (`app.html`).
90
91**Available Template Context:**
92- `app` - Current app name (auto-injected from URL)
93- `day` - Current day as YYYYMMDD string (auto-injected from URL for apps with `date_nav: true`)
94- `facets` - List of active facet dicts: `[{name, title, color, emoji}, ...]`
95- `selected_facet` - Currently selected facet name (string or None)
96- `app_registry` - Registry with all apps (usually not needed directly)
97- `state.journal_root` - Path to journal directory
98- Any variables passed from route handler via `render_template(...)`
99
100**Note:** The server-side `selected_facet` is also available client-side as `window.selectedFacet` (see JavaScript APIs below).
101
102**Vendor Libraries:**
103- Use `{{ vendor_lib('marked') }}` for markdown rendering
104- See [VENDOR.md](VENDOR.md) for available libraries
105
106**Reference implementations:**
107- Minimal: `apps/home/workspace.html` (simple content)
108- Styled: `apps/support/workspace.html` (custom CSS, forms, interactive JS)
109- Data-driven: `apps/todos/workspace.html` (facet sections, dynamic rendering)
110
111---
112
113## Optional Files
114
115### 2. `routes.py` - Flask Blueprint
116
117Define custom routes for your app (API endpoints, form handlers, navigation routes).
118
119**Key Points:**
120- **Not needed for simple apps** - the shared handler at `/app/{app_name}` serves your workspace automatically
121- Only create `routes.py` if you need custom routes beyond the index page
122- Blueprint variable must be named `{app_name}_bp`
123- Blueprint name must be `"app:{app_name}"`
124- URL prefix convention: `/app/{app_name}`
125- Access journal root via `state.journal_root` (always available)
126- Import utilities from `convey.utils` (see [Flask Utilities](#flask-utilities))
127
128**Reference implementations:**
129- API endpoints: `apps/search/routes.py` (search APIs, no index route)
130- Form handlers: `apps/todos/routes.py` (POST handlers, validation, flash messages)
131- Navigation: `apps/activities/routes.py` (date-based routes with custom context)
132- Redirects: `apps/todos/routes.py` index route (redirects `/` to today's date)
133
134
135
136### 3. `app.json` - Metadata
137
138Override default icon, label, and other app settings.
139
140**Authoritative source:** See the `App` dataclass in `apps/__init__.py` for all supported fields, types, and defaults.
141
142**Common fields:**
143- `icon` - Emoji icon for menu bar (default: "📦")
144- `label` - Display label in menu (default: title-cased app name)
145- `facets` - Enable facet integration (default: true)
146- `date_nav` - Show date navigation bar (default: false)
147- `allow_future_dates` - Allow clicking future dates in month picker (default: false)
148
149**When to disable facets:** Set `"facets": false` for apps that don't use facet-based organization (e.g., system settings, dev tools).
150
151**Examples:** Browse `apps/*/app.json` for reference configurations.
152
153### 4. `app_bar.html` - Bottom Bar Controls
154
155Fixed bottom bar for forms, buttons, date pickers, search boxes.
156
157**Key Points:**
158- App bar is fixed to bottom when present
159- Page body gets `has-app-bar` class (adjusts content margin)
160- Only rendered when app provides this template
161- Great for persistent input controls across views
162
163**Date Navigation:**
164
165Enable via `"date_nav": true` in `app.json` (not via includes). This renders a `← Date →` control with month picker. Requires `/app/{app_name}/api/stats/{month}` endpoint returning `{YYYYMMDD: count}` or `{YYYYMMDD: {facet: count}}`.
166
167Keyboard shortcuts: `←`/`→` for day navigation, `t` for today.
168
169### 5. `background.html` - Background Service
170
171JavaScript service that runs globally, even when app is not active.
172
173**AppServices API:**
174
175**Core Methods:**
176- `AppServices.register(appName, service)` - Register background service
177
178**Badge Methods:**
179
180App icon badges (menu bar):
181- `AppServices.badges.app.set(appName, count)` - Set app icon badge count
182- `AppServices.badges.app.clear(appName)` - Remove app icon badge
183- `AppServices.badges.app.get(appName)` - Get current badge count
184
185Facet pill badges (facet bar):
186- `AppServices.badges.facet.set(facetName, count)` - Set facet badge count
187- `AppServices.badges.facet.clear(facetName)` - Remove facet badge
188- `AppServices.badges.facet.get(facetName)` - Get current badge count
189
190Both badge types appear as red notification counts.
191
192**Notification Methods:**
193- `AppServices.notifications.show(options)` - Show persistent notification card
194- `AppServices.notifications.dismiss(id)` - Dismiss specific notification
195- `AppServices.notifications.dismissApp(appName)` - Dismiss all for app
196- `AppServices.notifications.dismissAll()` - Dismiss all notifications
197- `AppServices.notifications.count()` - Get active notification count
198- `AppServices.notifications.update(id, options)` - Update existing notification
199
200**Notification Options:**
201```javascript
202{
203 app: 'my_app', // App name (required)
204 icon: '📬', // Emoji icon (optional)
205 title: 'New Message', // Title (required)
206 message: 'You have...', // Message body (optional)
207 action: '/app/todos', // Click action URL (optional)
208 facet: 'work', // Auto-select facet on click (optional)
209 badge: 5, // Badge count (optional)
210 dismissible: true, // Show X button (default: true)
211 autoDismiss: 10000 // Auto-dismiss ms (optional)
212}
213```
214
215**WebSocket Events (`window.appEvents`):**
216- `listen(tract, callback)` - Listen to specific tract ('cortex', 'indexer', 'observe', etc.)
217- `listen('*', callback)` - Listen to all events
218- Messages have structure: `{tract: 'cortex', event: 'agent_complete', ...data}`
219- See [CALLOSUM.md](CALLOSUM.md) for event protocol details
220
221**Reference implementations:**
222- `apps/todos/background.html` - App icon badge with API fetch
223
224**Implementation source:** `convey/static/app.js` - AppServices framework, `convey/static/websocket.js` - WebSocket API
225
226---
227
228### 6. `tools.py` - App Tool Functions
229
230Define plain callable tool functions for your app in `tools.py`.
231
232**Key Points:**
233- Only create `tools.py` if your app needs reusable tool functions for agent workflows
234- Keep functions simple: typed inputs, dict-style outputs, clear docstrings
235- Put shared logic in your app/module layer and call it from these functions
236
237**Reference implementations:**
238- `apps/todos/tools.py`
239- `apps/entities/tools.py`
240
241---
242
243### 7. `call.py` - CLI Commands
244
245Define CLI commands for your app that are automatically discovered and available via `sol call <app> <command>`.
246
247**Key Points:**
248- Only create `call.py` if your app needs human-friendly CLI access to its operations
249- Export an `app = typer.Typer()` instance with commands defined via `@app.command()`
250- Automatically discovered and mounted at startup
251- Errors in one app's CLI don't prevent other apps from loading
252- CLI commands call the same data layer as `tools.py` but print formatted console output
253
254**Required export:**
255```python
256import typer
257
258app = typer.Typer(help="Description of your app commands.")
259```
260
261**Command pattern:** Define commands using Typer's `@app.command()` decorator with `typer.Argument` for positional args and `typer.Option` for flags. Call the underlying data layer directly (not tool helper wrappers) and print output via `typer.echo()`.
262
263**CLI vs tool functions:** CLI commands parallel tool functions but are optimized for interactive terminal use. Key differences:
264- Tool functions may accept a `Context` parameter for caller metadata; CLI has no context object
265- Print formatted text instead of returning dicts
266- Use `typer.Exit(1)` for errors instead of returning error dicts
267
268**Discovery behavior:** The `sol call` dispatcher scans `apps/*/call.py` at startup, imports modules, and mounts any `app` variable that is a `typer.Typer` instance as a sub-command. Private apps (directories starting with `_`) are skipped.
269
270**Reference implementations:**
271- Discovery logic: `think/call.py` - `_discover_app_calls()` function
272- App CLI example: `apps/todos/call.py` - Todo list command
273
274**Skills app reference:** `apps/skills/call.py` is the current owner-wide pattern for a data-backed app CLI. It exposes `sol call skills list|show|observe|seed|promote|refresh|mark-dormant|retire|edit-request|rename` and routes all writes through `think/skills.py`, which owns `journal/skills/patterns.jsonl`, `journal/skills/edit_requests.jsonl`, and `journal/skills/{slug}.md`. The shipped daily talents for this app live in `apps/skills/talent/skill_observer.md` (daily cogitate, priority 41) and `apps/skills/talent/skill_editor.md` + `skill_editor.py` (daily generate, priority 60). The observer marks patterns for creation/refresh, and the editor consumes those flags or pending `edit-request` rows to write/update exactly one owner-wide profile per run.
275
276---
277
278### 8. `talent/` - App Generators
279
280Define custom generator prompts that integrate with solstone's output generation system.
281
282**Key Points:**
283- Create `talent/` directory with `.md` files containing JSON frontmatter
284- App generators are automatically discovered alongside system generators
285- Keys are namespaced as `{app}:{agent}` (e.g., `my_app:weekly_summary`)
286- Outputs go to `JOURNAL/YYYYMMDD/talents/_<app>_<agent>.md` (or `.json` if `output: "json"`)
287
288**Metadata format:** Same schema as system generators in `talent/*.md` - JSON frontmatter includes `title`, `description`, `color`, `schedule` (required), `priority` (required for scheduled prompts), `hook`, `output`, `max_output_tokens`, and `thinking_budget` fields. The `schedule` field must be `"segment"` or `"daily"`. The `priority` field is required for all scheduled prompts - prompts without explicit priority will fail validation. Set `output: "json"` for structured JSON output instead of markdown. Optional `max_output_tokens` sets the maximum response length; `thinking_budget` sets the model's thinking token budget (provider-specific defaults apply if omitted). Generators reject a `cwd` field entirely; working-directory control is only available for `type: "cogitate"` prompts.
289
290**Priority bands:** Prompts run in priority order (lowest first). Recommended bands:
291- 10-30: Generators (content-producing prompts)
292- 40-60: Analysis agents
293- 90+: Late-stage agents
294- 99: Fun/optional prompts
295
296**Schedule extraction via hooks:** The live built-in extraction hook is `schedule`:
297
298- `"hook": {"post": "schedule"}` - Writes future scheduled items to `facets/{facet}/activities/{target_day}.jsonl` as anticipated activity records
299
300Example:
301
302```json
303{
304 "title": "Schedule Extractor",
305 "schedule": "daily",
306 "hook": {"post": "schedule"}
307}
308```
309
310**App-data outputs:** For outputs from app-specific data (not transcripts), store in `JOURNAL/apps/{app}/talents/*.md` - these are automatically indexed.
311
312**Template variables:** Generator prompts can use template variables like `$name`, `$preferred`, `$daily_preamble`, and context variables like `$day` and `$day_YYYYMMDD`. See [PROMPT_TEMPLATES.md](PROMPT_TEMPLATES.md) for the complete template system documentation.
313
314**Custom hooks:** Both generators and tool-using agents support custom `.py` hooks for transforming inputs and outputs programmatically. Hooks support both pre-processing (before LLM call) and post-processing (after LLM call):
315
316**Hook configuration:**
317- Use `"hook": {"pre": "my_hook"}` for pre-processing hooks
318- Use `"hook": {"post": "my_hook"}` for post-processing hooks
319- Use both together: `"hook": {"pre": "prep", "post": "process"}`
320- Use `"hook": {"flush": true}` to opt into segment flush (see below)
321- Resolution: `"name"` → `talent/{name}.py`, `"app:name"` → `apps/{app}/talent/{name}.py`, or explicit path
322
323**Pre-hooks** (`pre_process`): Modify inputs before the LLM call
324- `context` is the full config dict with: `name`, `use_id`, `provider`, `model`, `prompt`, `system_instruction` (if set), `user_instruction`, `output`, `meta`, and for generators: `day`, `segment`, `span`, `span_mode`, `transcript`, `output_path`
325- Return a dict of modified fields to merge back (e.g., `{"prompt": "modified"}`)
326- Return `None` for no changes
327
328**Post-hooks** (`post_process`): Transform output after the LLM call
329- `result` is the LLM output (markdown or JSON string)
330- `context` is the full config dict with: `name`, `use_id`, `provider`, `model`, `prompt`, `output`, `meta`, and for generators: `day`, `segment`, `span`, `span_mode`, `transcript`, `output_path`
331- Return modified string, or `None` to use original result
332
333**Flush hooks:** Segment agents can declare `"hook": {"flush": true}` to participate in segment flush. When no new segments arrive for an extended period, the supervisor triggers `sol think --flush --segment <last>`, which runs only flush-enabled agents with `context["flush"] = True` and `context["refresh"] = True`. This lets agents close out dangling state (e.g., end active activities that would otherwise wait indefinitely for the next segment). The timeout is managed by the supervisor — agents should trust the flush signal without their own timeout logic.
334
335Hook errors are logged but don't crash the pipeline (graceful degradation).
336
337```python
338# talent/my_hook.py
339def pre_process(context: dict) -> dict | None:
340 # Modify inputs before LLM call
341 return {"prompt": context["prompt"] + "\n\nBe concise."}
342
343def post_process(result: str, context: dict) -> str | None:
344 # Transform output after LLM call
345 return result + "\n\n## Generated by hook"
346```
347
348**Hook idempotency:** Post-hooks that write to shared journal state must be safe to run more than once on the same inputs. `sol think --refresh` bypasses the "output already exists" early-return in `think/talents.py` and re-executes the talent, which re-fires `post_process` against a fresh LLM result — so any side-effect the hook performs (writing events, appending to a log, updating an index file) will happen again. Pick one of these two patterns:
349
350- **Natural-key dedup.** Read the existing output, compute a natural key per row (e.g., `(facet, event_day, title, start, end)` for facet events), skip rows already present, and append only the new ones. Use this when the output is append-only history and you want to preserve prior writes from other agents.
351- **Atomic replace.** Recompute the full output, write it to a temp file, and rename into place. `atomic_write()` in `think/entities/core.py` is the established helper for text outputs; for JSONL, write the full set of lines to a tempfile and `os.replace()`. Use this when the hook owns the file end-to-end.
352
353(Retired 2026-04-18 Sprint 4.) An earlier `write_events_jsonl` hook in `think/hooks.py` opened facet-event logs in `"a"` mode with no dedup and doubled row counts on every `sol think --refresh` — see the 2026-04-17 layer-violations audit (V6) in the sol pbc internal extro repo (`vpe/workspace/solstone-layer-violations-audit.md`) for the full write-up.
354
355See `docs/coding-standards.md` L8/L9 for the broader principles.
356
357**Reference implementations:**
358- System generator templates: `talent/*.md` (files with `schedule` field but no `tools` field)
359- Schedule hook: `talent/schedule.py`
360- Discovery logic: `think/talent.py` - `get_talent_configs(has_tools=False)`, `get_output_name()`
361- Hook loading: `think/talent.py` - `load_pre_hook()`, `load_post_hook()`
362
363---
364
365### 9. `talent/` - App Agents and Generators
366
367Define custom agents and generator templates that integrate with solstone's Cortex agent system.
368
369**Key Points:**
370- Create `talent/` directory with `.md` files containing JSON frontmatter
371- Both agents and generators live in the same directory - distinguished by frontmatter fields
372- Agents have a `tools` field, generators have `schedule` but no `tools`
373- App agents/generators are automatically discovered alongside system ones
374- Keys are namespaced as `{app}:{name}` (e.g., `my_app:helper`)
375- Agents inherit all system agent capabilities (tools, scheduling, multi-facet)
376
377**Metadata format:** Same schema as system agents in `talent/*.md` - JSON frontmatter includes `title`, `provider`, `model`, `tools`, `schedule`, `priority`, `multi_facet`, `max_output_tokens`, and `thinking_budget` fields. The `priority` field is **required** for all scheduled prompts - prompts without explicit priority will fail validation. See the priority bands documentation in [THINK.md](THINK.md#unified-priority-execution). Optional `max_output_tokens` sets the maximum response length; `thinking_budget` sets the model's thinking token budget (provider-specific defaults apply if omitted; OpenAI uses fixed reasoning and ignores this field). Cogitate agents may also declare `cwd: "journal"` or `cwd: "repo"`; when omitted they default to `journal`, and repo-oriented prompts like `coder` should opt into `repo`. See [CORTEX.md](CORTEX.md) for agent configuration details.
378
379**Template variables:** Agent prompts can use template variables like `$name`, `$preferred`, and pronoun variables. See [PROMPT_TEMPLATES.md](PROMPT_TEMPLATES.md) for the complete template system documentation.
380
381**Reference implementations:**
382- System agent examples: `talent/*.md` (files with `tools` field)
383- Discovery logic: `think/talent.py` - `get_talent_configs(has_tools=True)`, `get_talent()`
384
385#### Prompt Context Configuration
386
387Both generators and agents support an optional `load` key for configuring source data dependencies:
388
389```json
390{
391 "load": {"transcripts": true, "percepts": false, "talents": {"screen": true}}
392}
393```
394
395- `load` controls which source types are clustered before generator execution. Values can be:
396 - `false` - don't load this source type
397 - `true` - load if available
398 - `"required"` - load, and skip generation if no content found (useful for generators that only make sense with specific input types, e.g., `"audio": "required"` for speaker detection)
399 - For `agents` only: a dict for selective filtering, e.g., `{"entities": true, "meetings": "required", "flow": false}`. Keys are agent names (system) or `"app:agent"` (app-namespaced). An empty dict `{}` means no agents.
400
401Context is provided inline in the `.md` body via template variables:
402
403- `$facets` - focused facet context or all available facets
404- `$activity_context` - activity metadata, segment state, and analysis focus sections
405
406**Authoritative source:** `think/talent.py` - `_DEFAULT_LOAD`, `source_is_enabled()`, `source_is_required()`, `get_talent_filter()`
407
408---
409
410### 10. `talent/` - Agent Skills
411
412Define [Agent Skills](https://agentskills.io/specification) as subdirectories within `talent/`. Skills package procedural knowledge, workflows, and resources that AI coding agents (Claude Code, GitHub Copilot, Gemini CLI, etc.) can discover and use on demand.
413
414**Key Points:**
415- Create a subdirectory in `talent/` with a `SKILL.md` file (YAML frontmatter + markdown body)
416- The directory name must match the `name` field in the YAML frontmatter
417- Skill names must be unique across system `talent/` and all `apps/*/talent/` directories
418- `make skills` discovers all skills and symlinks them into `journal/.agents/skills/` and `journal/.claude/skills/`
419- Skills are standalone — they don't interact with the talent agent/generator system
420- The talent loader ignores subdirectories, so skills won't interfere with agent discovery
421
422**Directory structure:**
423```
424talent/my-skill/
425├── SKILL.md # Required: YAML frontmatter + instructions
426├── scripts/ # Optional: Executable code (Python, Bash, etc.)
427├── references/ # Optional: Additional documentation loaded on demand
428└── assets/ # Optional: Static resources (templates, data files)
429```
430
431**SKILL.md format:**
432```yaml
433---
434name: my-skill
435description: Short description of what this skill does and when to use it.
436---
437
438# Instructions
439
440Step-by-step procedures, examples, and domain knowledge for the agent.
441```
442
443**Required frontmatter fields:**
444- `name` — Max 64 chars, lowercase letters + numbers + hyphens, must match directory name
445- `description` — Max 1024 chars, describes what the skill does *and when to use it*
446
447**Optional frontmatter fields:**
448- `license` — License name (e.g., `Apache-2.0`)
449- `compatibility` — Max 500 chars, environment requirements
450- `metadata` — Arbitrary key-value string map
451- `allowed-tools` — Space-delimited list of pre-approved tools (experimental)
452
453**App skills** work the same way — place a skill directory inside `apps/my_app/talent/`:
454```
455apps/my_app/talent/my-skill/
456├── SKILL.md
457└── references/
458```
459
460**Running `make skills`:** Discovers all `SKILL.md` files under `talent/*/` and `apps/*/talent/*/`, then creates symlinks in `journal/.agents/skills/` and `journal/.claude/skills/` so that all supported coding agents see the same skills. Errors if two skills share the same directory name.
461
462---
463
464### 11. `maint/` - Maintenance Tasks
465
466Define one-time maintenance scripts that run automatically when supervisor starts.
467
468**Key Points:**
469- Create `maint/` directory with standalone Python scripts (each with a `main()` function)
470- Scripts are discovered and run in sorted order by filename (use `000_`, `001_` prefixes for ordering)
471- Completed tasks tracked in `<journal>/maint/{app}/{task}.jsonl` - runs once per journal
472- Exit code 0 = success, non-zero = failure (failed tasks can be re-run with `--force`)
473- Use `setup_cli()` for consistent argument parsing and logging
474
475**CLI:** `sol maint` (run pending), `sol maint --list` (show status), `sol maint --force` (re-run all)
476
477**Reference implementations:**
478- Example task: `apps/entities/maint/001_migrate_to_journal_entities.py` - real migration task demonstrating maint patterns
479- Discovery logic: `think/maint.py` - `discover_tasks()`, `run_task()`
480
481---
482
483### 12. `tests/` - App Tests
484
485Apps can include their own tests that are discovered and run separately from core tests.
486
487**Key Points:**
488- Create `tests/` directory with `conftest.py` and `test_*.py` files
489- App fixtures should be self-contained (only use pytest builtins like `tmp_path`, `monkeypatch`)
490- Tests run via `make test-apps` (all apps) or `make test-app APP=my_app`
491- Integration tests can use `@pytest.mark.integration` but live in the same flat structure
492
493**Directory structure:**
494```
495apps/my_app/tests/
496├── __init__.py
497├── conftest.py # Self-contained fixtures
498└── test_*.py # Test files
499```
500
501**Reference implementations:**
502- Fixture patterns: `apps/todos/tests/conftest.py`
503- Tool testing: `apps/todos/tests/test_tools.py`
504
505---
506
507### 13. `events.py` - Server-Side Event Handlers
508
509Define server-side handlers that react to Callosum events. Handlers run in Convey's thread pool, enabling reactive backend logic without creating new services.
510
511**Key Points:**
512- Create `events.py` with functions decorated with `@on_event(tract, event)`
513- Handlers receive an `EventContext` with `msg`, `app`, `tract`, `event` fields
514- Discovered at Convey startup; events processed serially with 30s timeout per handler
515- Errors are logged but don't affect other handlers or the web server
516- Wildcards supported: `@on_event("*", "*")` matches all events
517
518**Available imports** (same as route handlers):
519- `from convey import state` - Access `state.journal_root`
520- `from convey import emit` - Emit events back to Callosum
521- `from apps.utils import get_app_storage_path, log_app_action` - App storage
522- `from convey.utils import load_json, save_json, spawn_agent` - Utilities
523
524**Not available** (no Flask request context):
525- `request`, `session`, `current_app`
526- `error_response()`, `success_response()`, `parse_pagination_params()`
527
528**Reference implementations:**
529- Framework: `apps/events.py` - `EventContext` dataclass, decorator, discovery
530- Example: `apps/entities/events.py` - Entity activity tracking via event handlers
531
532---
533
534## Flask Utilities
535
536Available in `convey/utils.py`:
537
538### Route Helpers
539- `error_response(message, code=400)` - Standard JSON error response
540- `success_response(data=None, code=200)` - Standard JSON success response
541- `parse_pagination_params(default_limit, max_limit, min_limit)` - Extract and validate limit/offset from request.args
542
543### Date Formatting
544- `format_date(date_str)` - Format YYYYMMDD as "Wednesday January 14th"
545
546### Agent Spawning
547- `spawn_agent(prompt, name, provider, config)` - Spawn Cortex agent, returns use_id
548
549### JSON Utilities
550- `load_json(path)` - Load JSON file with error handling (returns None on error)
551- `save_json(path, data, indent, add_newline)` - Save JSON with formatting (returns bool)
552
553**See source:** `convey/utils.py` for full signatures and documentation
554
555### App Storage
556
557Apps can persist journal-specific configuration and data in `<journal>/apps/<app_name>/`:
558
559```python
560from apps.utils import get_app_storage_path, load_app_config, save_app_config
561```
562
563- `get_app_storage_path(app_name, *sub_dirs, ensure_exists)` - Get Path to app storage directory
564- `load_app_config(app_name, default)` - Load app config from `config.json`
565- `save_app_config(app_name, config)` - Save app config to `config.json`
566
567**See source:** `apps/utils.py` for implementation details
568
569### Action Logging
570
571Apps that modify owner data should log actions for audit trail purposes:
572
573```python
574from apps.utils import log_app_action
575```
576
577- `log_app_action(app, facet, action, params, day=None)` - Log owner-initiated action
578
579**Parameters:**
580- `app` - App name where action originated
581- `facet` - Facet where action occurred, or `None` for journal-level actions
582- `action` - Action type using `{domain}_{verb}` naming (e.g., `entity_add`, `todo_complete`)
583- `params` - Action-specific parameters dict
584- `day` - Optional day in YYYYMMDD format (defaults to today)
585
586**Facet-scoped vs journal-level:**
587- Pass a facet name for facet-specific actions (todos, entities, etc.)
588- Pass `facet=None` for journal-level actions (settings, observers, etc.)
589
590Log after successful mutations, not attempts.
591
592---
593
594## Think Module Integration
595
596Available functions from the `think` module:
597
598### Facets
599`think/facets.py`: `get_facets()` - Returns dict of facet configurations
600
601### Todos
602`apps/todos/todo.py`:
603- `get_todos(day, facet)` - Get todo list for day and facet
604- `TodoChecklist` class - Load and manipulate todo markdown files
605
606### Entities
607`think/entities/`: `load_entities(facet)` - Load entities for a facet
608
609See [talent/journal/SKILL.md](../talent/journal/SKILL.md), [CORTEX.md](CORTEX.md), [CALLOSUM.md](CALLOSUM.md) for subsystem details.
610
611---
612
613## JavaScript APIs
614
615### Global Variables
616
617Defined in `convey/templates/app.html`:
618- `window.facetsData` - Array of facet objects `[{name, title, color, emoji}, ...]`
619- `window.selectedFacet` - Current facet name or null (see Facet Selection below)
620- `window.appFacetCounts` - Badge counts for current app `{"work": 5, "personal": 3}` (set via route's `facet_counts`)
621
622### Facet Selection
623
624Apps can access and control facet selection through a uniform API:
625- `window.selectedFacet` - Current facet name or null (initialized by server, updated on change)
626- `window.selectFacet(name)` - Change selection programmatically
627- `facet.switch` CustomEvent - Dispatched when selection changes
628 - Event detail: `{facet: 'work' or null, facetData: {name, title, color, emoji} or null}`
629
630**Facet Modes:**
631- **all-facet mode**: `window.selectedFacet === null`, show content from all facets
632- **specific-facet mode**: `window.selectedFacet === "work"`, show only that facet's content
633- Selection persisted via cookie, synchronized across facet pills
634
635**UX Tip:** Apps should provide visual indication when in all-facet mode vs showing a specific facet. For example, group items by facet, show facet badges/colors on items, or display a subtle "All facets" label. This helps owners understand the scope of what they're viewing.
636
637**See implementation:** `convey/static/app.js` - Facet switching logic and event dispatch
638
639**Disabled mode:** On apps with `facets.disabled: true`, the facet bar is visible but inert — pills render without interactivity or tab stops. The container is marked `aria-hidden="true"` so screen readers skip it. The bar remains visually present as always-visible chrome.
640
641### WebSocket Events (Client-Side)
642
643`window.appEvents` API defined in `convey/static/websocket.js`:
644- `listen(tract, callback)` - Subscribe to specific tract or '*' for all events
645- Messages structure: `{tract: 'cortex', event: 'agent_complete', ...data}`
646
647**Common tracts:** `cortex`, `indexer`, `observe`, `task`
648
649See [CALLOSUM.md](CALLOSUM.md) for complete event protocol.
650
651### Server-Side Events
652
653Emit Callosum events from route handlers using `convey.emit()`:
654
655```python
656from convey import emit
657
658@my_bp.route("/action", methods=["POST"])
659def handle_action():
660 # ... process request ...
661
662 # Emit event (non-blocking, drops if disconnected)
663 emit("my_app", "action_complete", item_id=123, status="success")
664
665 return jsonify({"status": "ok"})
666```
667
668**Behavior:**
669- Non-blocking: queues message for background thread
670- If Callosum disconnected, message is dropped (with debug logging)
671- Returns `True` if queued, `False` if bridge not started or queue full
672
673**Reference implementations:** `apps/import/routes.py`, `apps/observer/routes.py`
674
675---
676
677## CSS Styling
678
679### Workspace Containers
680
681**Always wrap your workspace content** in one of these standardized containers for consistent spacing and layout:
682
683**For readable content** (forms, lists, messages, text):
684```html
685<div class="workspace-content">
686 <!-- Your app content here -->
687</div>
688```
689
690**For data-heavy content** (tables, grids, calendars):
691```html
692<div class="workspace-content-wide">
693 <!-- Your app content here -->
694</div>
695```
696
697**Key differences:**
698- `.workspace-content` - Centered with 1200px max-width, ideal for readability
699- `.workspace-content-wide` - Full viewport width, ideal for data tables and grids
700- Both include consistent padding and mobile responsiveness
701
702**See:** `convey/static/app.css` for implementation details
703
704**Examples:**
705- Standard: `apps/home/workspace.html`, `apps/todos/workspace.html`, `apps/entities/workspace.html`
706- Wide: `apps/search/workspace.html`, `apps/activities/_day.html`, `apps/import/workspace.html`
707
708### CSS Variables
709
710Dynamic variables based on selected facet (update automatically on facet change):
711
712```css
713:root {
714 --facet-color: #3b82f6; /* Selected facet color */
715 --facet-bg: #3b82f61a; /* 10% opacity background */
716 --facet-border: #3b82f6; /* Border color */
717}
718```
719
720Use these in your app-specific styles to respond to facet theme.
721
722### App-Specific Styles
723
724**Best practice:** Scope styles with unique class prefix to avoid conflicts.
725
726**Example:** `apps/stats/workspace.html` shows scoped `.stats-*` classes for all custom styles in its `<style>` block.
727
728### Global Styles
729
730Main stylesheet `convey/static/app.css` provides base components. Review for available classes and patterns.
731
732---
733
734## Common Patterns
735
736### Date-Based Navigation
737See `apps/todos/routes.py:todos_day()` - Shows date validation and `format_date()` usage. Day navigation is handled automatically by the date_nav component.
738
739### AJAX Endpoints
740See `apps/todos/routes.py:move_todo()` - Shows JSON parsing, validation, `error_response()`, `success_response()`.
741
742### Form Handling with Flash Messages
743See `apps/todos/routes.py:todos_day()` POST handler - Shows form processing, validation, flash messages, redirects.
744
745### Facet-Aware Queries
746See `apps/todos/routes.py:todos_day()` - Loads data per-facet when selected, or all facets when null.
747
748### Facet Pill Badges
749Pass `facet_counts` dict to `render_template()` to show initial badge counts on facet pills:
750```python
751facet_counts = {"work": 5, "personal": 3}
752return render_template("app.html", facet_counts=facet_counts)
753```
754For client-side updates (e.g., after completing a todo), use `AppServices.badges.facet.set(facetName, count)`.
755
756See `apps/todos/routes.py:todos_day()` - Computes pending counts from already-loaded data.
757
758---
759
760## Debugging Tips
761
762### Check Discovery
763
764```bash
765# Start Convey with debug logging
766FLASK_DEBUG=1 convey
767
768# Look for log lines:
769# "Discovered app: my_app"
770# "Registered blueprint: app:my_app"
771```
772
773### Common Issues
774
775| Issue | Cause | Fix |
776|-------|-------|-----|
777| App not discovered | Missing `workspace.html` | Ensure workspace.html exists |
778| Blueprint not found (with routes.py) | Wrong variable name | Use `{app_name}_bp` exactly |
779| Import error (with routes.py) | Blueprint name mismatch | Use `"app:{app_name}"` exactly |
780| Hyphens in name | Directory uses hyphens | Rename to use underscores |
781| Custom routes don't work | URL prefix mismatch | Check `url_prefix` matches pattern |
782
783### Logging
784
785Use `current_app.logger` from Flask for debugging. See `apps/todos/routes.py` for examples.
786
787---
788
789## Best Practices
790
7911. **Use underscores** in directory names (`my_app`, not `my-app`)
7922. **Wrap workspace content** in `.workspace-content` or `.workspace-content-wide`
7933. **Scope CSS** with unique class names to avoid conflicts
7944. **Validate input** on all POST endpoints (use `error_response`)
7955. **Check facet selection** when loading facet-specific data
7966. **Use state.journal_root** for journal path (always available)
7977. **Pass facet_counts** from routes if app has per-facet counts
7988. **Handle errors gracefully** with flash messages or JSON errors
7999. **Test facet switching** to ensure content updates correctly
80010. **Use background services** for WebSocket event handling
80111. **Follow Flask patterns** for blueprints, url_for, etc.
802
803---
804
805## Example Apps
806
807Browse `apps/*/` directories for reference implementations. Apps range in complexity:
808
809- **Minimal** - Just `workspace.html` (e.g., `apps/home/`, `apps/health/`)
810- **Styled** - Custom CSS, background services (e.g., `apps/support/`)
811- **Full-featured** - Routes, forms, AJAX, badges, tools (e.g., `apps/todos/`, `apps/entities/`)
812
813---
814
815## Additional Resources
816
817- **`apps/__init__.py`** - App discovery and registry implementation
818- **`convey/apps.py`** - Context processors and vendor library helper
819- **`convey/templates/app.html`** - Main app container template
820- **`convey/static/app.js`** - AppServices framework
821- **`convey/static/websocket.js`** - WebSocket event system
822- [../AGENTS.md](../AGENTS.md) - Project development guidelines and standards
823- [storage.md](../talent/journal/references/storage.md) - Journal directory structure and data organization
824- [CORTEX.md](CORTEX.md) - Agent system architecture and spawning agents
825- [CALLOSUM.md](CALLOSUM.md) - Message bus protocol and WebSocket events
826
827For Flask documentation, see [https://flask.palletsprojects.com/](https://flask.palletsprojects.com/)