obsidian-systemsculpt-ai: Instructions file for Codex

SystemSculpt AI Obsidian Plugin

Canonical repository guidance for the SystemSculpt Obsidian client. CLAUDE.md is a symlink to this file; edit this file only.

Repository boundary

The SystemSculpt workspace has three sibling repositories:

• ~/gits/systemsculpt/plugin — this Obsidian client.
• ~/gits/systemsculpt/website — the customer website and first-party API.
• ~/gits/systemsculpt/systemsculpt-os — growth and operator automation.

The plugin is a thin, vault-native client. It owns Obsidian integration, presentation, local vault tool implementations, approval UX and enforcement, a reconnecting server-protocol client, user-visible local cache/export state, and portable Studio behavior. It does not own an agent loop, continuation policy, provider retry, compaction, prompt caching, authoritative chat sessions, provider SDKs, provider credentials, model catalogs, marketing operations, or a local AI runtime.

All AI traffic uses the first-party SystemSculpt API at https://systemsculpt.com/api/plugin. OpenRouter and server agent implementation details stay behind that interface.

Server-upgrade independence

This is a release requirement, not an implementation preference:

• The boundary applies to ChatView, Audio Processor, transcription, document processing, images, embeddings, Studio AI, and future managed AI features. The client may capture or select local input bytes, upload them, render progress, obtain local approval, and save or apply a returned result. Provider calls, models, prompts, chunking, polling, retry, transforms, job orchestration, caching, billing, and durable execution state stay server-side.
• Harness, model, provider, retry, caching, compaction, memory, session, and orchestration changes must be deployable server-side without a plugin release.
• The plugin wire contract is harness-agnostic. Production client code, headers, persisted data, UI labels, and tool results must not contain Pi, Think, OpenRouter, AI SDK, or another harness/provider identity.
• The plugin never decides whether the agent should continue. It receives a typed client-tool request, applies local approval policy, executes the Obsidian operation, and returns one typed result. The server decides every subsequent model step.
• The server owns the authoritative conversation session and ordered event history. Local chat persistence is a cache or user export and must never become execution authority after reconnect.
• Client capability negotiation is additive. The plugin advertises supported local tool names and contract versions; the server adapts its tool catalog to that manifest. Unknown additive event fields and unknown server-only tools must not crash or stop the client.
• One migration release may replace the legacy client continuation loop with this thin protocol bridge. The first released thin-client artifact then becomes a permanent compatibility fixture. Every later server agent change must connect, render, execute its supported local tools, reconnect, and finish a long turn against that unchanged artifact.
• A plugin update is justified only by a new or changed local Obsidian capability, a client security correction, or an intentionally new UI feature. A server harness replacement is never sufficient justification.