Imported from abundance-ds/shoulders (AGENTS.md). Install upstream with npx skills add abundance-ds/shoulders. Copyright stays with the author.

Shoulders

Do not add Co-Authored-By lines to git commit messages.

An AI workspace for researchers. Handles Markdown, LaTeX, DOCX, Jupyter notebooks, CSV, and code in a single environment with integrated reference management, multi-provider AI, and version control.

Central documentation registry: docs/MAP.md — start here when looking for anything.

Architecture

Tauri v2 Shell
  Rust Backend (src-tauri/src/)
    fs_commands.rs  — File I/O, file watching, API proxy, content search, shell commands
    git.rs          — Git operations via git2 crate (no OS git dependency)
    chat.rs         — AI streaming proxy (SSE via reqwest + tokio)
    pty.rs          — Terminal sessions via portable-pty
    kernel.rs       — Jupyter kernel protocol (ZeroMQ), kernel discovery/launch/execute
    typst_export.rs — Markdown → Typst → PDF (5 templates, citation-gated bibliography)
    latex.rs        — LaTeX compilation via Tectonic, SyncTeX
    usage_db.rs     — Usage tracking SQLite at ~/.shoulders/usage.db
    lib.rs          — App setup, state management, command registration, OS keychain (keyring)

  Vue 3 Frontend (src/)
    stores/         — Pinia: workspace, files, editor, chat, tasks, reviews, links, usage, kernel, typst, latex, references, toast, environment
    services/       — AI providers, chat orchestration, git, GitHub sync, references, system prompt, auth, code runner, telemetry
    editor/         — CodeMirror 6: setup, theme, ghost suggestions, diff overlay, tasks, wiki links, citations, live preview, code chunks
    components/     — Vue components: layout, sidebar, editor, right panel, modals, settings
    utils/          — Helpers: chatMarkdown, fileTypes, notebookFormat, textDiff, errorMessages

  Web Backend (web/)  — Optional Nuxt 3 server powering shoulde.rs (auth, admin, AI proxy, peer review)

Desktop shell is Tauri v2 (Rust + webview). All file operations and API calls go through custom Rust commands — no browser filesystem access, no CORS issues. The frontend is Vue 3 + Pinia + Tailwind CSS 3.

Key Systems

AI Chat

Multi-provider streaming chat in the right sidebar with parallel sessions.

• Providers: Anthropic, OpenAI, Google (configured in ~/.shoulders/models.json + ~/.shoulders/keys.env)
• 29 tools across 6 categories:
  • Workspace (10): read_file, list_files, search_content, write_file, edit_file, rename_file, move_file, duplicate_file, delete_file, run_command
  • References (5): search_references, get_reference, add_reference, cite_reference, edit_reference
  • Comments (4): add_comment, reply_to_comment, resolve_comment, create_proposal
  • Notebooks (6): read_notebook, edit_cell, run_cell, run_all_cells, add_cell, delete_cell
  • Web (3): web_search, search_papers, fetch_url
  • Creation (1): generate_image
• Streaming: AI SDK (Chat composable → ToolLoopAgent → streamText()) → tauriFetch → Rust proxy (chat.rs) → Tauri events
• Sessions: persist to .shoulders/chats/, close/reopen via history dropdown
• System prompt: services/systemPrompt.js — shared base for chat and ghost
• Skills: .project/skills/ — user-defined skill manifests injected into system prompt
• Context: services/workspaceMeta.js builds <workspace-meta> (open tabs, git diff) appended to system prompt
• Sidebar: AISidebar.vue — 5-screen view router (Home / New / Conversation / Workflow / Terminal). Home: unified session list (active + older from disk). New: ChatInput hero + workflow/agent launcher. Drill-ins use v-show (Home, Conversation) or v-if (New, Workflow, Terminal).
• Prompts: stores/prompts.js — built-in defaults + user CRUD, persists to .shoulders/prompts.json. PROMPTS tab removed from sidebar; usePrompt() navigates to New screen with prefill.
• Image gen: generate_image tool uses Gemini 3.1 Flash Image (gemini-3.1-flash-image-preview) via proxy_api_call_full. Saves to workspace root, stores only file path in chat history (no base64 in messages). Display: GeneratedImageBlock.vue loads from disk.
• Model migration: MODELS_VERSION in workspace.js — upgrades old model IDs in ~/.shoulders/models.json in-place on workspace open. See ai-system.md — Adding or Updating Models.

Edit Review Workflow

When an AI agent or the built-in AI chat edits files, changes are queued in .shoulders/pending-edits.json and shown as inline diffs (accept/reject via merge view).

• External agents: intercepted by PreToolUse hooks (e.g. .claude/hooks/intercept-edits.sh)
• Built-in chat: edit_file and write_file tools record edits directly via reviews store
• Race condition fix: update filesStore.fileContents[path] BEFORE recording pending edit

Toggle "direct mode" in the footer to let edits through without review.

Shoulders Tool API

When the app is running, workspace tools (references, paper search, comments, notebooks, canvas) are available as a local HTTP API. See .shoulders/tool-api.md for usage and the full tool list. Auth token is in .shoulders/tool-server-token.

Config Directories

• .shoulders/ — private AI state (gitignored): system.md, pending-edits.json, .direct-mode, chats/, comments.json, open-sessions.json
• .project/ — public project data (syncs via git): references/, styles/, skills/, pdf-settings.json, citation-style.json
• ~/.shoulders/ — global config: keys.env (API keys), models.json, usage.db

Commands

bun install
npx tauri dev          # Development (hot-reload)
npx tauri build        # Production build
bun run build          # Frontend only
cargo build --manifest-path src-tauri/Cargo.toml  # Rust backend only

Releasing

Do NOT run gh release create or create GitHub releases manually. CI handles everything.

To release a new version:

1. Bump the version in all three files: package.json, src-tauri/tauri.conf.json, src-tauri/Cargo.toml
2. Commit and push to main
3. Tag and push: git tag v<version> && git push --tags
4. Stop. CI (.github/workflows/build.yml) builds all platforms, signs the binaries, creates the release with installers, publishes it, and deletes the previous release.

The auto-updater (shoulde.rs/api/v1/updates/latest.json) serves the latest.json asset from the latest published GitHub release. A manually created release without signed assets will break the update flow for all users.

Key Gotchas

See docs/gotchas.md for the full list. Critical ones:

• SuperDoc + Vue Proxy: SuperDoc uses #private class fields — NEVER put instances in ref() or reactive(). Use shallowRef + markRaw().
• invoke() struct args: When Rust command takes request: MyStruct, JS MUST pass { request: { ... } } — NOT flat args.
• CM6 full-doc swap kills position tracking: Use computeMinimalChange() (src/utils/textDiff.js) for surgical diffs.
• RightPanel overflow-hidden clips popovers: Use <Teleport to="body"> with position: fixed for any dropdown inside the right panel.
• NEVER use tauri-plugin-stronghold: Stronghold.load() takes ~50 seconds. Use keyring crate instead.
• Shoulders proxy URL: Single source of truth in apiClient.js:SHOULDERS_PROXY_URL.