# dsh-md-notes User Guide > [中文](usage.zh.md) · English A note-taking plugin for DeepSeek Harness (DSH). This guide covers **everything** the plugin can do — from your first note to syncing notes with Git. It assumes the plugin is installed (see [README](../README.md)). **In a nutshell**: notes are plain `.md` files stored under each workspace's `.dsh-notes/` directory. You can write them here, capture conversations into them, and — optionally — back them up / sync them with a Git repository. --- ## 1. Where your notes live - Every dsh **workspace** has its own notes folder: `/.dsh-notes/`. - Each note is a plain `.md` file. Open and edit it with any editor — the plugin picks up your changes the next time it reads the file. - `meta.json` in the same folder is just a cache of titles/timestamps; ignore it (it's never committed to Git). > Notes are **workspace-bound**: without a workspace there's nowhere to store > them — create a workspace in the dsh sidebar first. ## 2. Opening the notes manager Click the **notes entry** at the bottom of the sidebar. A full-screen manager opens with two columns: - **Left — note list**, grouped by workspace. Each workspace row has a folder icon, a collapse arrow, and a **+** button to create a note in that workspace (with Git enabled it also carries update/push icon buttons — see [§5](#5-git-sync-optional)). - **Right — note content**, with **Preview / Edit** tabs and a **Save** button. **Clicking an existing note opens Preview by default**; a newly created note opens directly in Edit mode. ### Creating a note Click **+** on a workspace row. A note is created with an auto title ("Untitled note ") and **opens directly in Edit mode**. ### Editing & previewing - **Preview** tab: see the rendered result (GFM tables / task lists / math / code highlighting) — shown by default when you open an existing note. - **Edit** tab: write markdown source. - **Save**: writes to the local `.md` file and refreshes the list. ### Deleting a note Hover a note in the list and click the 🗑 icon. A confirmation dialog asks for confirmation (deleting cannot be undone). ### While a note is being written While a note is being written (save / capture), that note **cannot be edited** (locked across sessions) until the write finishes. ## 3. Capturing a conversation into a note Below any assistant answer, click the **notes icon** (next to the copy button). A picker opens: 1. Choose an existing note — the list shows **all workspaces' notes**, grouped by workspace (fold/collapse a workspace row to browse; the current workspace's notes are included), or create a new one on the spot with the **+** button on any workspace row. A note that is currently being written is **not selectable** (it shows a row loading) — writes are mutually exclusive per note across sessions. 2. Click **Write to note**. The question + answer text is captured from the conversation itself (instant, no waiting) and appended to the note as a timestamped section; while the write runs the button reads "Writing…", and on success a green "Written ✓" appears left of the button before the picker closes: ```markdown --- ## -- ### 👤 ### 🤖 ``` ## 4. Referencing notes in a conversation (@) Type **`@`** in the chat input to pick a note: the pick inserts a **note chip**, and on send the note's **content** is put into the model context automatically — the model can see and cite the note without you having to tell it to read files. ### 4.1 Picking a note 1. Type `@` → the candidate menu lists notes of the **current workspace** (📝 prefix; the title is the primary row, the file name the secondary line). 2. Select with arrows / click → a note chip appears; keep typing `@` to add more. 3. Keep typing to **filter** the candidates (by title or file name). ### 4.2 Referencing notes from other workspaces - Type a partial workspace name (e.g. `@dsh-pl`) → a **workspace row** appears (`dsh-plugin/`, 🗂️ icon); - **Pick the workspace row** → it auto-completes to `@dsh-plugin/` and **immediately lists that workspace's notes**; keep typing to filter within it; - An exact workspace name (`@dsh-plugin`) switches directly; - **Chinese workspace names (no spaces) work**; only names **containing spaces** cannot be triggered by text (dsh's trigger token stops at whitespace — a platform limit; a menu-based all-workspaces picker is planned). ### 4.3 What happens on send Two things: 1. **Your message keeps a readable reference line** (standard markdown link syntax) — e.g. `Referenced note [title](.dsh-notes/note.md)` (same workspace) or `Referenced note [title](../other-dir/.dsh-notes/note.md)` (cross-workspace) — it tells the model (and you) which note was referenced; 2. **The host injects the note's content into the model context** — a collapsible "context injection" row (source `md-notes`) appears in the chat; expand it to see the injected content. The model gets the content directly — it does **not** depend on calling its `read` tool itself. ### 4.4 Common questions - **No need to re-reference for follow-ups**: the injected content stays in the session context (until dsh compacts old history), so follow-up questions (e.g. "what was X in the note?") work without re-referencing. If a note is large and you worry about context usage, start a new session or reference only the notes you need. - **Note deleted / moved**: if the note no longer exists at send time, the send is blocked with "«name» could not be found. Remove the reference." — delete the stale chip and resend. - **A typed `@note-title` does nothing**: plain-text `@note-title` is only a highlight decoration — it does **not** enter the model context; real references go through the menu (chip). - **No workspace**: sessions without a workspace get no `@` candidates (silent). ## 5. Git sync (optional) Git sync keeps your notes backed up and synchronized across machines. The plugin manages a local **clone** of your repository automatically — you only need to give it a repository **URL**. > **Notes always live locally in `/.dsh-notes`**. Git sync only > pushes them to / pulls them from a repository; it never changes where notes > are stored locally. ### 5.1 Two modes (choose one) In the settings panel (see [§6](#6-the-settings-panel)), pick a mode: | Mode | What it does | Configure | |---|---|---| | **Off** | No Git sync. Notes are just local files. | — | | **Shared repo** | One repository for all workspaces. Each workspace's notes sync into that repo's branch under a folder named after the workspace. | Repo URL + optional branch (default `main`) | | **Own repos** | Each workspace has its own repository. | Per workspace: repo URL + branch (default `main`) + in-repo subpath (default repo root) | > Want a single repository for everything? Use **Shared repo** — every > workspace gets its own folder automatically. Want different repos per > project? Use **Own repos**. ### 5.2 Pushing notes 1. Open any note and click **Push** (next to Save) — or click the **push icon** on a workspace row in the note list. 2. A small panel asks for a commit message (default "Notes update