Update to Memova.ai

{
  "description": "Use when the user explicitly invokes Memova to set up, create, inspect, or connect a user-owned Memova managed knowledge-base root from Codex, especially after an iOS setup session has been marked ready for Codex.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 475
    },
    {
      "relative_path": "scripts/create_memova_vault.py",
      "size_in_bytes": 4151
    },
    {
      "relative_path": "scripts/diagnose_memova_vault.py",
      "size_in_bytes": 8060
    },
    {
      "relative_path": "scripts/find_vault_locations.py",
      "size_in_bytes": 1965
    },
    {
      "relative_path": "scripts/inspect_vault.py",
      "size_in_bytes": 748
    },
    {
      "relative_path": "scripts/memova_vault_lib.py",
      "size_in_bytes": 97146
    },
    {
      "relative_path": "scripts/setup_fixture_harness.py",
      "size_in_bytes": 50807
    },
    {
      "relative_path": "scripts/validate_memova_vault.py",
      "size_in_bytes": 2681
    }
  ],
  "name": "memova-vault-setup",
  "skill_md_contents": "---\nname: memova-vault-setup\ndescription: Use when the user explicitly invokes Memova to set up, create, inspect, or connect a user-owned Memova managed knowledge-base root from Codex, especially after an iOS setup session has been marked ready for Codex.\n---\n\n# Memova Vault Setup\n\nUse this skill only when the user explicitly invokes Memova vault setup, selects a Memova setup\nstarter prompt, or asks Codex to create/connect a Memova knowledge base. Do not invoke it just\nbecause a prompt mentions Obsidian, iCloud, or notes.\n\n## Operating Rules\n\n- Treat the Memova MCP setup package as the source of truth for template version, setup mode,\n  storage target, path hints, and V3/V4 filesystem operations. V2 remains supported for existing\n  setup sessions; V3/V4 are never reconstructed from plugin-hardcoded templates.\n- Do not plan or create local setup files if the Memova MCP setup package cannot be retrieved. A\n  missing MCP tool, failed OAuth flow, empty pending setup list, or invalid setup package is a hard\n  stop, not permission to fall back to local defaults.\n- Never report knowledge-base setup as complete unless `complete_knowledge_base_setup` succeeded in\n  the same workflow. Local directory validation alone is only \"local validation OK\"; it is not a\n  completed Memova setup and may not be enough for iOS to bind the current setup session.\n- Before starting setup on every invocation, run the plugin version check from the plugin root:\n\n  ```bash\n  python3 plugins/memova/scripts/version_check.py\n  ```\n\n  If it returns `should_remind: true`, show its message and continue the requested setup workflow.\n  If the check fails or returns no reminder, continue silently. Never run the upgrade command\n  without explicit user confirmation.\n- Use the helper scripts in this skill for path discovery, vault inspection, file creation, and\n  validation instead of hand-writing large file trees. Resolve `scripts/...` paths relative to this\n  skill directory.\n- Default to iCloud Drive on Mac. Google Drive and OneDrive are deferred.\n- Never write outside the user-approved target directory.\n- Do not overwrite existing user files by default. Create missing files and record skipped files.\n  The exception is Memova setup identity manifests (`_memova/manifest.json`): when a user reuses a\n  Memova directory for a new setup session, this file must be refreshed to the current MCP setup\n  package before reporting success.\n- For `create_new_vault`, create the exact V2, V3, or V4 root requested by the current setup package. The\n  target folder itself is the Memova managed root.\n- For `connect_existing_vault`, preserve the user's existing vault root and create only a root-level\n  Memova managed sub-knowledge-base at `<existing vault>/Memova`. Do not write into or reorganize the\n  user's other vault folders.\n- The setup output must be self-describing. V2 uses the plugin's compatibility templates. V3/V4 use\n  only the backend-provided `vault_contract.memova_managed_root.setup_operations`, including file\n  contents, hashes, byte sizes, write modes, and preservation rules. Do not replace these with empty\n  placeholders or locally invented V3/V4 files. In particular, never duplicate the V4 tree or\n  `projects/Uncategorized/` as Plugin constants; create exactly the backend package operations.\n- These setup docs and schemas are Memova-managed setup files. Existing files are skipped by\n  default; overwrite them only with explicit user approval and `--overwrite-machine-files`, for\n  example when repairing docs created by an older plugin version.\n- Local validation dispatches by the setup/manifest template version. V2 reports\n  `memova_kb_v2_validation_result_v1`; V3/V4 report their matching versioned validation result.\n  All use `ok`, `repair_required`, or `blocked`. V3/V4 repair requires current backend-supplied\n  setup/repair operations; never synthesize their repair contents locally.\n- Setup should create `inbox/meetings/` but must not pre-create concrete meeting packet folders; iOS\n  writes those later after each meeting.\n- Ask for explicit user approval before creating files, writing into an existing vault, or using a\n  non-iCloud target for an iCloud setup.\n- Never store secrets, OAuth tokens, raw credentials, or full private note contents in progress\n  payloads.\n\n## Default Workflow\n\nWhen the user asks to set up their Memova knowledge base:\n\n1. Run the plugin version check described above.\n2. Call `list_pending_knowledge_base_setups` as the setup workflow's first MCP read. If Codex needs\n   Memova OAuth and the tool is exposed, let this call trigger that browser login/consent flow.\n   If this MCP tool is not exposed in the current thread, run `codex mcp list` before giving\n   recovery instructions:\n   - If `memova` is listed with Auth `Not logged in`, run the bundled helper from the plugin root:\n\n     ```bash\n     python3 plugins/memova/scripts/ensure_mcp_login.py\n     ```\n\n     This helper starts `codex mcp login memova --scopes ...` and attempts to open exactly one\n     browser authorization URL. The user still has to approve Memova OAuth in the browser. If\n     automatic browser opening fails, tell the user to copy the printed `authorization_url` into a\n     browser. If the helper returns `manual_terminal_login_required`, show its exact top-level\n     `manual_login_command` and tell the user to run it in a normal system Terminal/PowerShell\n     outside the Codex task. Do not retry the helper or ask the user to clear OAuth/browser state or\n     change sandbox settings. If it reports `login_completed_client_refresh_required`, say OAuth\n     succeeded and do not ask the user to log in again. After either successful-login status,\n     require a full Codex restart and a new task if the current task still does not expose the\n     Memova setup tools; Codex does not refresh MCP tool availability mid-task.\n   - If `memova` is not listed, stop and tell the user to upgrade/reinstall the Memova plugin, then\n     restart Codex or start a new thread.\n   Do not use the filesystem helper scripts without the MCP package. In the final answer for this\n   path, do not say \"setup complete\", \"locally set up\", or \"mark complete\"; say that setup is\n   blocked because the current Codex thread cannot access the Memova setup MCP tools.\n3. If there is exactly one ready/running setup, use it.\n   If there are no pending setups, stop and tell the user to create/mark a setup package from the\n   Memova app first, or disconnect/reconnect Memova OAuth in Codex with the same Memova account used\n   in the iOS app. If there are multiple, summarize them and ask which one to run. Then show the ids\n   of the other ready/running sessions and ask for adjacent confirmation before marking them\n   superseded. Only after that confirmation, call `fail_knowledge_base_setup` for the unselected\n   sessions, using:\n   - `failure_code`: `setup.superseded_by_selected_session`\n   - `failure_message`: `Superseded because the user selected another knowledge-base setup session.`\n   - `payload`: include `selected_setup_session_id` and `discarded_setup_session_id`\n\n   Continue only with the selected setup session. If the user does not approve superseding the\n   others, leave them unchanged and say they may appear again on the next setup run.\n4. Call `get_knowledge_base_setup_context` for the selected `setup_session_id`.\n5. Call `append_knowledge_base_setup_progress` with a concise message that setup has started.\n6. Write the MCP `setup_package` object to a temporary JSON file under `/tmp`, then run:\n\n   ```bash\n   python3 scripts/find_vault_locations.py \\\n     --setup-json \"/tmp/memova-setup.json\"\n   ```\n\n   Use the output plus the setup package path hints to identify likely iCloud / existing vault\n   locations. If the path is still unclear, ask the user for the Mac path.\n7. If the user supplied an old vault path, run:\n\n   ```bash\n   python3 scripts/inspect_vault.py --path \"<old-vault-path>\"\n   ```\n\n   Keep inspection light; do not recursively read the full vault unless the user asks.\n8. Run a dry plan with the same MCP setup package:\n\n   - For `create_new_vault`, the target root is the new vault root, usually\n     the discovery output's `recommended_new_vault`. If the setup package includes\n     `target_path_hints.desired_input_folder_name`, that value names the new vault folder, for\n     example `<iCloud>/Test111`.\n   - For `connect_existing_vault`, the target root is the final Memova managed-root folder:\n     `<existing vault>/Memova`. Never target the existing vault root itself.\n\n   ```bash\n   python3 scripts/create_memova_vault.py plan \\\n     --setup-json \"/tmp/memova-setup.json\" \\\n     --target-root \"<approved-target-path>\"\n   ```\n\n9. Confirm `vault_template_version` is V2, V3, or V4. For V3/V4, stop if the package lacks valid\n   `setup_operations` or if any content hash/byte count fails validation. Then summarize the plan:\n   target path, setup mode, target kind, non-iCloud warning if any,\n   directories to create, files to create, files to skip, the self-describing setup docs/schemas to\n   create, and the Memova managed-root relative path.\n10. Ask for approval. Only after approval, run:\n\n   ```bash\n   python3 scripts/create_memova_vault.py create \\\n     --setup-json \"/tmp/memova-setup.json\" \\\n     --target-root \"<approved-target-path>\" \\\n     --confirm-create\n   ```\n\n11. Validate the result:\n\n    ```bash\n    python3 scripts/validate_memova_vault.py \\\n      --path \"<approved-target-path>\" \\\n      --setup-json \"/tmp/memova-setup.json\" \\\n      --require-setup-identity\n    ```\n\n12. Confirm validation reports `status == \"ok\"`, `setup_completion_eligible == true`, no\n    completion blockers, no missing required documentation/schema/manifest/sync-state files, and\n    `identity_validation.status == \"ok\"`. This proves the local manifest ids and\n    `setup_session_id` match the current backend setup package. If identity validation fails, do\n    not call `complete_knowledge_base_setup`; repair or fail the setup.\n13. Call `complete_knowledge_base_setup` with a small result summary:\n    `manifest_id`, `vault_manifest_id`, `input_root_manifest_id`,\n    `memova_input_root_relative_path`, `selected_by`, `target_path_summary`,\n    `ios_folder_binding_hints`, `created_file_count`, `created_dir_count`, `written_files`,\n    `skipped_file_count`, `validation_status`, and `identity_validation`.\n14. Mark this Mac as setup-complete for future non-setup workflow reminders:\n\n    ```bash\n    python3 plugins/memova/scripts/kb_setup_reminder.py \\\n      --mark-complete \\\n      --backend-completed \\\n      --setup-session-id \"<setup_session_id>\" \\\n      --vault-path \"<approved-target-path>\"\n    ```\n\n15. If setup cannot proceed, call `fail_knowledge_base_setup` with a clear failure code such as\n    `setup.path_not_found`, `setup.user_declined`, `setup.validation_failed`, or\n    `setup.write_failed`.\n\n## Target Path Guidance\n\n- Common iCloud Drive path on Mac:\n  `~/Library/Mobile Documents/com~apple~CloudDocs`\n- If the setup package has `target_path_hints.desired_input_folder_name`, use that value as the\n  create-new-vault folder name. Example: `desired_input_folder_name: Test111` maps to\n  `~/Library/Mobile Documents/com~apple~CloudDocs/Test111`.\n- If no desired folder name is present, the default new-vault target is:\n  `~/Library/Mobile Documents/com~apple~CloudDocs/Memova Vault`\n- Do not assume iOS and Mac expose the same absolute path. The shared identity is the Memova\n  `_memova/manifest.json`, not the path string.\n- Include `ios_folder_binding_hints` from the helper result when completing setup. iOS uses these\n  hints to ask the user for one Files folder authorization, then automatically resolve likely\n  manifest paths relative to the authorized folder.\n- If the user provides a path manually, expand `~`, inspect it, and show the resolved path before\n  writing.\n\n## Final Response\n\nEnd with:\n\n- setup session id,\n- target path summary,\n- manifest id,\n- input root manifest id,\n- Memova managed-root relative path,\n- iOS authorization hint summary, especially the iCloud relative managed-root path when available,\n- created/skipped counts,\n- validation result,\n- backend completion result. If `complete_knowledge_base_setup` was not called and did not\n  succeed, explicitly say \"backend setup is incomplete\" and do not say setup is complete,\n- what the iOS app should do next: authorize the same vault/managed-root folder through Files and\n  verify the Memova `_memova/manifest.json`.\n"
}