AI Assistant Screph - workspace, context and actions

1. Setup and activation

Under LLM Settings, create or test a profile and assign models to assistant and, when those contextual flows are needed, cv, codegen and semantic_selection. Ollama or LM Studio can be used for local operation.
Open AI ASSISTANT → AI assistant and enable it. The default activation mode is Button only; proactive hints are enabled separately.
In Selector, the same flag is exposed as the AI header toggle. Open the assistant with the AI button, Ctrl+Shift+Space, or a context entry point for the selected object.
In the Settings window, the Assistant button is in the status bar. The Selector voice button passes recognized text as a task and requires a configured speech provider.

2. What the workspace contains

Tab	Purpose
Chat	Task input, model response and a selector for the shared `assistant` LLM role. Contextual CV, codegen or voice flows may use other assignments from LLM Settings.
Hints	Proactive candidates that can be accepted, moved to chat or dismissed.
Actions	Preview/apply cards with action kind, target, policy state and Edit, Reject, Confirm/Apply or Revert controls.
Sessions / Timeline	Session search and a timeline of turns, hints, decisions and action results.
Context	The active surface, competence, subject and project path used by the current turn.
Artifacts	References to module-produced results; heavy bodies remain with their owning modules and are not loaded automatically.
Settings	The same activation, context, competence, policy and history controls without leaving the workspace.

3. Competencies and routing

A contextual entry point selects a competence; it does not grant unrestricted access. Available competencies cover Canvas/regions, CV, Screph Code, voice tasks, Capture/timeline, Tree modules/exports, Automation Runtime, settings/dependencies, account/crash support and i18n/docs. The page exposes competence toggles, but the current router does not consume them, so they cannot yet be treated as runtime blocks.

The internal assistant role determines instructions and action scope: assistant, canvas, cv, codegen, semantic_selection, capture, tree_modules, automation, settings_dependencies, support or i18n_docs. For LLM profile selection, cv, codegen and semantic_selection use their matching assignments; all other competencies use the assistant LLM role.

4. Preview, policy and confirmation

A model response may propose only an action with a registered stable identifier. An unknown action fails explicitly.
The router validates required inputs and the policy gate before invoking an adapter.
Medium-, high- and destructive-risk actions, plus actions carrying a separate permission flag, are blocked with requires_confirmation until explicitly confirmed.
The card persists the preview and the user's decision. If the adapter provides a revert token, the result can be reverted from the workspace.

5. Context, attachments and privacy

The default payload is Text only; images and artifacts are disabled by default.
Artifacts require per-turn consent by default. Without consent, the handoff includes allowed data only and reports blocked references.
The default attachment retention policy is Metadata only. Thumbnail mode creates local thumbnails, while full-project-artifacts copies resolvable files into session storage. Lowering the mode does not delete copies or thumbnails already materialized.
Context is redacted before the LLM handoff; the workspace can show a compact redaction report.

6. What the settings actually apply

Group	Current boundary
Activation and proactive hints	`enabled`, launcher visibility, the workspace gate and proactive priority/cooldown/snooze/repeat have consumers and are re-read by their UI/runtime paths.
Context and action policy	These work, but some values are cached when the runtime is created. Changes made in the workspace's embedded page refresh that runtime; after editing the standalone Settings page, restarting Screph is the safe boundary.
Workspace presentation	Default view, long-task routing and timeline/context-chip/cost toggles are currently persisted-only. The workspace restores its last tab from local state and still constructs those panes.
Competencies and Assistant LLM routing	The visible controls persist but do not alter the current router. Assign models through the shared LLM roles.
History and CV extras	Action-history retention, mirroring and automatic turn docs are captured when the runtime is created. The CV auto-save/export-preview controls have no consumer. Separate session-pruning and project-mirror limits are described below.

7. History and diagnostics

The workspace stores prompts and responses, sessions, turns, action records, context and timeline metadata and permitted attachments under ScrephData/runtime/ai_assistant. history.jsonl applies its saved retention as events are appended, but session-directory cleanup currently does not receive that field through typed runtime settings and effectively uses 180 days when a workspace is created. The active session and sessions with unresolved confirmation-required actions are not removed by that pass.

The project mirror lives under <project>/.screph_ai_assistant and is not removed by global 180-day pruning. In the current implementation, the mirroring control affects the action-history store, while the generic workspace creates its own store with mirroring enabled by default: this control cannot be treated as a way to stop all new messages.mirror.jsonl, timeline.mirror.jsonl and actions.mirror.jsonl writes. It does not delete existing records either.

Retention, exceptions and complete cleanup →

If the Assistant does not start, check the Enable assistant flag, Enable workspace, the required shared LLM-role assignment, profile availability and the action policy gate. A competence toggle cannot currently be the blocking cause because the router does not read it. Screph reports runtime failures explicitly and does not silently switch provider or action.