{"record":{"id":"c338158bdec75e2d","repo":"zeroclaw-labs/zeroclaw","slug":"alias-name-not-found-optional","errorCode":null,"errorMessage":"[{alias}] {name} not found (optional)","messagePattern":"\\[(.+?)\\] (.+?) not found \\(optional\\)","errorType":"console","errorClass":"DiagItem","httpStatus":null,"severity":"warning","filePath":"crates/zeroclaw-runtime/src/doctor/mod.rs","lineNumber":1545,"sourceCode":"        check_agent_file(&agent_ws, \"AGENTS.md\", alias, cat, items);\n    }\n}\n\n/// Existence check for an optional per-agent workspace file. Prefixes the\n/// owning agent alias as `[alias]` so a multi-agent report stays legible and\n/// `(optional)` keeps its single, consistent meaning as the severity hint\n/// (e.g. `[default] SOUL.md present`, `[default] AGENTS.md not found (optional)`).\nfn check_agent_file(\n    workspace_dir: &Path,\n    name: &str,\n    alias: &str,\n    cat: &'static str,\n    items: &mut Vec<DiagItem>,\n) {\n    if workspace_dir.join(name).is_file() {\n        items.push(DiagItem::ok(cat, format!(\"[{alias}] {name} present\")));\n    } else {\n        items.push(DiagItem::warn(\n            cat,\n            format!(\"[{alias}] {name} not found (optional)\"),\n        ));\n    }\n}\n\nfn disk_available_mb(path: &Path) -> Option<u64> {\n    let output = std::process::Command::new(\"df\")\n        .arg(\"-m\")\n        .arg(path)\n        .output()\n        .ok()?;\n    if !output.status.success() {\n        return None;\n    }\n    let stdout = String::from_utf8_lossy(&output.stdout);\n    parse_df_available_mb(&stdout)\n}","sourceCodeStart":1527,"sourceCodeEnd":1563,"githubUrl":"https://github.com/zeroclaw-labs/zeroclaw/blob/88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc/crates/zeroclaw-runtime/src/doctor/mod.rs#L1527-L1563","documentation":"A `zeroclaw doctor` warning from `check_agent_file` (via `check_workspace`): an optional per-agent workspace file — `SOUL.md` or `AGENTS.md` — is missing from the agent's workspace directory (`config.agent_workspace_dir(alias)`) for an enabled agent. The `(optional)` suffix is deliberate: the agent runs without it, but the persona/instruction layer doctor expects is absent. Items are prefixed `[alias]` so multi-agent reports stay legible.","triggerScenarios":"Running `zeroclaw doctor` when an enabled agent's workspace directory exists but lacks `SOUL.md` or `AGENTS.md` (checked with `workspace_dir.join(name).is_file()`).","commonSituations":"Fresh agent created via config without running the init/quickstart that writes persona files; workspace directory moved or recreated; agents migrated to a new `data_dir` without copying persona files.","solutions":["If you want the persona/instruction layer, create the named file in the agent's workspace directory (the one `zeroclaw doctor` reports against).","Re-run `zeroclaw doctor` to confirm the item flips to `[alias] SOUL.md present`.","If the file is intentionally absent, ignore the warning — it is explicitly marked optional."],"exampleFix":"# before: agent workspace has no SOUL.md\n# doctor: [default] SOUL.md not found (optional)\n\n# after\nprintf '# Persona\\nYou are a concise, helpful assistant.\\n' \\\n  > \"$ZEROCLAW_DATA_DIR/agents/default/SOUL.md\"","handlingStrategy":"fallback","validationCode":null,"typeGuard":"fn agent_file_present(workspace_dir: &std::path::Path, name: &str) -> bool {\n    workspace_dir.join(name).is_file()\n}","tryCatchPattern":null,"preventionTips":["Provision SOUL.md/AGENTS.md as part of agent creation, not as an afterthought.","When migrating data_dir, copy persona files along with state."],"tags":["workspace","agents","doctor","optional-files","zeroclaw"],"backgroundTag":"file-not-found","analyzedSha":"88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc","analyzedAt":"2026-08-23T01:07:41.857Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}