# YodaMan Manual

Local-first workspace intelligence with chat, search, mandatory Graphify knowledge graphs, supervised agent automation, plugins, desktop controls, VS Code commands, and mobile pairing.

Version 0.3.4

## 1. Setup

Install Context Expert, OpenSpec, Graphify, install dependencies, and start the runtime from the project root.

    npm install -g @contextexpert/cli
    npm install -g @fission-ai/openspec@latest
    python3 -m pip install graphifyy
    npm install
    sh setup.sh
    npm start

The backend runtime listens on `http://localhost:3090`. The development web UI listens on `http://localhost:5190`. Use `npm run desktop` for the Electron app.

## 2. Core ideas

### Local runtime

One private Express runtime powers the web UI, desktop app, VS Code extension, mobile companion, plugins, and runtime API.

### Workspace control

Paste paths, browse folders in desktop clients, select, refresh, validate, edit, delete, and reindex absolute local workspace paths.

### Knowledge graph

Graphify builds required workspace graphs for graph-aware answers, impact analysis, freshness warnings, architecture maps, and CLI health checks with `yodaman doctor --graph`.

### Human-approved writes

Agent tasks use graph context, stream events, and pause for approval before applying file writes.

### Local persistence

Task history and audit logs persist in SQLite when available, with JSON fallback.

### Restricted plugins

Plugins declare permissions. Plugin uploads, unrestricted plugins, and agent shell commands are disabled by default and should only be enabled for trusted local support sessions.

### Crash recovery

The desktop recovery screen shows the logo, runtime logs, retry/status actions, and Copy Error.

## 3. Web UI

- Settings: Open from the top-right Settings button, sidebar plus button, or Configuration modal. Paste an absolute path or use Browse in the desktop app, then add, edit, and delete workspace paths.
- Workspaces: Select a project, refresh the workspace list, validate health, toggle inclusion, edit the file path, delete a workspace, and sync the selected repository.
- Chat: Ask questions using selected workspace context.
- Search: Run semantic search across indexed code and documentation, optionally scoped to the selected project.
- Dashboard: View status, database/index metrics, environment info, diagnostics, task counts, approvals, plugin policy, and mobile pairing.
- Logs: Open searchable runtime logs, reindex requests, index queue state, and `ctx index` output. Filter by text, level, severity, and user action before copying diagnostics.
- Manual: Read the in-app guide.
- Stardust: OpenSpec CLI wrapper for spec-driven development. Propose, validate, apply, and archive changes. Includes diagnostics, version checks, and one-click OpenSpec installation.
- Plugins: Upload JavaScript plugins, inspect permissions and parameters, refresh loaded plugins, and delete non-mandatory plugin files.
- Graph doctor: Run `yodaman doctor --graph` to check active graphs, persisted freshness, orphaned nodes, and the most dependency-heavy file.

## 4. Desktop app

The Electron app starts a managed runtime sidecar when no runtime is already available on port `3090`. It also runs from the system tray.

- `Restart Managed Runtime` restarts the managed backend.
- `Copy Mobile Pairing Link` creates and copies a `yodaman://pair` link.
- `Add Project Folder` opens a native folder picker.
- `Show YodaMan` restores the window from the tray.
- `Quit` stops the desktop app and managed runtime.

## 5. VS Code extension

The extension checks runtime status, starts the runtime command, adds workspaces by browsing, pasting, or using the current VS Code workspace, asks/searches/reindexes the current workspace, opens runtime logs, runs and cancels agent tasks, streams events, opens proposed writes as diffs, approves or rejects changes, clears task/audit history, and exposes the YodaMan activity bar sidebar.

## 6. Mobile companion

The mobile companion pairs with `yodaman://pair` links. It can check status, list projects, choose a workspace, ask, search, inspect task timelines, open event details, cancel active tasks, refresh pending approvals, and approve or reject proposed writes.

## 7. Runtime API highlights

- `GET/POST/PUT/DELETE /api/projects`: List, add, update, or remove workspace paths.
- `POST /api/reindex`: Queue a workspace for reindexing.
- `/api/graphify/*`: Read graph status, rebuild graphs, query relationships, explain nodes, find paths, run impact analysis, and load architecture maps.
- `GET /api/search` and `POST /api/ask`: Search and ask against indexed context.
- `GET /api/status` and `GET /api/desktop/diagnostics`: Read status and diagnostics.
- `GET/POST/DELETE /api/plugins`: Manage JavaScript plugins.
- `/api/agent/*`: Run, inspect, approve, reject, cancel, or clear agent tasks.
- `GET/DELETE /api/audit`: Inspect or clear audit logs.
- `POST /api/pairing`: Create mobile pairing links.

## 8. Troubleshooting

- Context Expert not found: Install `@contextexpert/cli` and confirm `ctx --version` works.
- Graphify not found: Install `graphifyy`, confirm `graphify --help` works, or set `YODAMAN_GRAPHIFY_BIN`.
- Graph health warnings: Run `yodaman doctor --graph`, then sync the affected workspace if orphaned nodes or missing graphs are reported.
- Runtime unreachable: Check port `3090`, restart the managed runtime, or run `yodaman` from Terminal.
- Moved repository: Open Settings, edit the workspace path, save, then sync.
- Search results are stale: Reindex the selected workspace.
- Mobile cannot connect: Use the desktop LAN IP, confirm firewall access to port `3090`, and generate a fresh pairing link.
- Plugin blocked: Add explicit permissions or intentionally allow unrestricted plugins.
- OpenSpec not found: Install `@fission-ai/openspec@latest` and confirm `openspec --version` works, or click "Install Now" in the Stardust tab.
- Crash screen: Use Copy Error to capture the message and logs.

## 9. Verification

    npm test
    npm run build
    npm run desktop:pack
    cd extensions/vscode-yodaman
    npm run lint
    npm run package

## 10. Stardust — OpenSpec Integration

YodaMan 0.3.4 integrates OpenSpec through the Stardust tab. OpenSpec provides structured spec-driven development with a propose → validate → apply → archive workflow.

### Setup

    npm install -g @fission-ai/openspec@latest

### Workflow

1. Propose: Create a new change proposal with a title, description, and spec path.
2. Validate: Check the change against your project's specs (supports `--strict` mode).
3. Apply: Apply the validated change (supports `--dry-run` for safety).
4. Archive: Archive a completed change.

### API Endpoints

- `GET /api/stardust/diagnose?projectRoot=...` — Run OpenSpec diagnostics
- `POST /api/stardust/run` — Execute any OpenSpec workflow action