# Octarine Skills — AI Assistant Integration Guide This file describes how AI coding assistants (Claude Code, Codex, Cursor, etc.) can interact with an Octarine workspace to save notes, daily entries, and other content. ## What is Octarine? Octarine is a local-first, privacy-focused note-taking and AI-assisted writing desktop app. All notes are stored as **plain Markdown files** on disk. Octarine watches the filesystem and automatically picks up any changes — so external tools can create and edit notes by simply writing `.md` files to the workspace folder. ## Workspace Discovery Before creating or editing notes, you must know the workspace path. Follow this order: 1. **Check stored preferences** — if the user has previously saved a workspace path to agent memory or config (e.g., CLAUDE.md, AGENTS.md, or the agent's memory system), use that. 2. **Check the current directory** — if the current working directory (or a parent) contains a `.octarine/` folder, treat it as the workspace root. 3. **Ask the user** — if no stored preference or `.octarine/` folder is found, ask the user to paste their Octarine workspace path. 4. **Validate** — confirm the provided path exists and contains a `.octarine/` directory before writing any files. If it doesn't, warn the user that the folder may not be an Octarine workspace. 5. **Save to memory (global)** — once the user provides a workspace path, persist it to your agent's **global** memory or config (not project-scoped) so it's available from any working directory in future sessions. **Never guess or assume a default path.** Always confirm the workspace before writing files. ### Common Workspace Locations - macOS: `~/Documents/Octarine/` or a custom folder - Linux: `~/Documents/Octarine/` or a custom folder - Windows: `C:\Users\\Documents\Octarine\` or a custom folder ## Folder Structure ``` / ├── *.md # Regular notes (root level) ├── /*.md # Notes organized in folders ├── Daily/ # Daily notes (YYYY-MM-DD.md) │ └── Weekly/ # Weekly notes (YYYY-[W]WW.md) ├── .templates/ # Note templates ├── .attachments/ # Images and media ├── .files/ # Imported non-markdown files └── .octarine/ # App config (DO NOT modify) ``` ## How to Save a Note Write a `.md` file to the workspace directory. Octarine's file watcher will detect it automatically. ### Basic Note ```markdown # My Note Title Content goes here. Standard markdown is fully supported. ``` Save as: `/My Note Title.md` ### Note with Frontmatter Octarine supports YAML frontmatter for structured metadata: ```markdown --- title: Meeting Notes author: Jane status: draft date: 2025-01-15 pinned: true custom_property: any value tags: - meetings - engineering --- # Meeting Notes Content here... ``` **Supported value types:** | Type | Example | |------|---------| | String | `status: draft` | | Number | `priority: 1` | | Boolean | `pinned: true` | | Date | `date: 2025-01-15` | | List | `tags:` followed by `- item` entries (see above) | **Special properties:** - `tags` — must be a YAML list of strings. Used for filtering and organization. - `pinned` — boolean. Pins the note to the top of the sidebar. - `locked` — boolean. Locks the note from editing. You can add any custom properties beyond these. Properties starting with `oct.` are reserved for internal use. --- ## Complete Markdown Syntax Reference Octarine extends standard markdown with several custom syntaxes. Below is every supported format. ### Standard Inline Formatting | Syntax | Result | |--------|--------| | `**bold**` | **bold** | | `*italic*` | *italic* | | `` `code` `` | inline code | | `~~strikethrough~~` | ~~strikethrough~~ | ### Underline Single tildes (without a color emoji) render as underline: ```markdown ~underlined text~ ``` **Important:** This is distinct from strikethrough (`~~double tilde~~`). A single `~` with no emoji prefix means underline. ### Colored Text Prefix text inside single tildes with a color emoji ball: ```markdown ~🔴red text~ ~🟠orange text~ ~🟡yellow text~ ~🟢green text~ ~🔵blue text~ ~🟣purple text~ ~🟤brown text~ ~🩷pink text~ ``` The color emoji must immediately follow the opening `~` with no space. ### Highlight (Colored Background) Wrap text with `==` and prefix with a color emoji for colored highlights: ```markdown ==🔴red highlight== ==🟠orange highlight== ==🟡yellow highlight== ==🟢green highlight== ==🔵blue highlight== ==🟣purple highlight== ==🟤brown highlight== ==🩷pink highlight== ``` Without an emoji prefix, `==text==` uses the default highlight color (purple). ### Tags Use `#hashtags` anywhere in the note body. Octarine extracts and indexes them automatically. Tags support Unicode, numbers, underscores, hyphens, and slashes. Nested tags can be created with `/` to build tag hierarchies: ```markdown Working on the new feature. #project #update #in-progress Nested tags: #priority/high #work/engineering/backend ``` ### Wiki Links Use `[[double brackets]]` to link between notes. **Links must use the full path relative to the workspace root** (without the workspace path itself). Always use `/` as the separator, even on Windows. ```markdown This relates to [[Engineering/API Design]] and [[Engineering/Database Schema]]. ``` If a note is in the workspace root, just use the filename: ```markdown See [[Quick Notes]] for details. ``` If a note is in a subfolder, include the full folder path: ```markdown See [[Projects/Alpha/design-doc]] for details. ``` **Important:** `[[Guide]]` looks for `Guide.md` in the workspace root. If the file is at `Engineering/Guide.md`, you must write `[[Engineering/Guide]]`. The `.md` extension is optional — Octarine appends it automatically. ### Task Lists Standard markdown checkboxes. Octarine tracks complete vs incomplete counts. ```markdown - [ ] Finish the report - [ ] Review pull request - [x] Send the email ``` ### Callouts Blockquote-based callout blocks with a type marker. Five types are supported: ```markdown > [!INFO] > This is an informational callout. > [!TIP] > A helpful tip for the reader. > [!WARNING] > Proceed with caution. > [!ERROR] > Something went wrong. > [!SUCCESS] > Operation completed successfully. ``` The type keyword is case-insensitive (`[!info]` works too). ### Math / LaTeX #### Block Math Use double dollar signs on their own lines for display math: ```markdown $$ E = mc^2 $$ ``` ```markdown $$ x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} $$ ``` Block math is rendered centered with KaTeX. Each `$$` delimiter must be on its own line. #### Inline Math Use single dollar signs for inline expressions: ```markdown The equation $E = mc^2$ is well known. ``` ### Code Blocks Standard fenced code blocks with language syntax highlighting: ````markdown ```javascript console.log('hello world'); ``` ```` Octarine supports syntax highlighting for many languages including JavaScript, TypeScript, Python, Rust, Go, Java, CSS, HTML, SQL, and more. #### Mermaid Diagrams Use the `mermaid` language tag to render diagrams: ````markdown ```mermaid graph TD A[Start] --> B{Decision} B -->|Yes| C[OK] B -->|No| D[End] ``` ```` ### Tables Standard markdown table syntax with resizable columns: ```markdown | Header 1 | Header 2 | Header 3 | |----------|----------|----------| | Cell 1 | Cell 2 | Cell 3 | | Cell 4 | Cell 5 | Cell 6 | ``` #### Column Width Persistence When columns are resized in the editor, Octarine saves widths as an HTML comment before the table: ```markdown | Header 1 | Header 2 | Header 3 | |----------|----------|----------| | Cell 1 | Cell 2 | Cell 3 | ``` The values are comma-separated pixel widths, one per column. If you want to set column widths programmatically, add this comment line immediately before the table. ### Images #### Local images (wikilink format) Save images to `.attachments/` and reference with wikilinks: ```markdown [[screenshot.png]] ``` With a custom width (in pixels): ```markdown [[screenshot.png|500]] ``` #### External images (standard markdown) ```markdown ![Alt text](https://example.com/image.png) ``` With a custom width (pipe in alt text): ```markdown ![Alt text|300](https://example.com/image.png) ``` **Supported image formats:** `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp` ### Videos Reference local videos with wikilinks. Save video files to `.attachments/`. ```markdown [[demo.mp4]] ``` With a custom width: ```markdown [[demo.mp4|600]] ``` **Supported video formats:** `.mp4`, `.webm`, `.mov` ### Horizontal Rule ```markdown --- ``` ### Blockquotes Standard blockquotes (without a callout type marker): ```markdown > This is a regular blockquote. > It can span multiple lines. ``` ### Template Variables Only applicable inside `.templates/` files. Use double curly braces. Only the following variables are supported: | Variable | Description | Default Format | |----------|-------------|----------------| | `{{title}}` | Note's title (filename without `.md`) | — | | `{{date}}` | Current date | `yyyy-MM-dd` | | `{{date:FORMAT}}` | Current date with custom format | User-specified | | `{{time}}` | Current time | `HH:mm` | | `{{time:FORMAT}}` | Current time with custom format | User-specified | Date and time formats use **date-fns** syntax. Examples: ```markdown {{date}} → 2025-01-15 {{date:MMMM d, yyyy}} → January 15, 2025 {{date:EEEE, do MMMM}} → Wednesday, 15th January {{time}} → 14:30 {{time:h:mm a}} → 2:30 PM ``` Unknown variables are left unchanged in the output. --- ## Creating Daily Notes Daily notes follow a strict naming convention and live in the `Daily/` folder. | Type | Folder | Filename Format | Example | |------|--------|----------------|---------| | Daily | `Daily/` | `YYYY-MM-DD.md` | `Daily/2025-01-15.md` | | Weekly | `Daily/Weekly/` | `YYYY-[W]WW.md` | `Daily/Weekly/2025-W03.md` | **Important:** Only files matching the expected date format are recognized as daily/weekly notes. ### Daily Note Example Save as `/Daily/2025-01-15.md`: ```markdown ## Tasks - [ ] Morning standup - [ ] Code review - [x] Deploy to staging ## Notes Had a productive meeting about #project-alpha. ``` The date heading is automatically displayed in the UI — no need to add a title or date frontmatter for daily notes. Just start with your content. ## Creating Notes in Subfolders You can organize notes in any subfolder structure. Just write the file to the desired path. ``` /Projects/Alpha/design-doc.md /Areas/Health/workout-log.md /Archive/old-notes.md ``` Octarine will detect new folders and files automatically. ## Saving Images and Attachments - **Images**: Save to `/.attachments/` - **Files**: Save to `/.files/` Reference images in notes with wikilinks: ```markdown [[my-image.png|500]] ``` Or standard markdown (for external URLs): ```markdown ![Alt text|500](https://example.com/image.png) ``` ## File Naming Rules - Use `.md` extension for all notes - Avoid special characters: `< > : " / \ | ? *` - Octarine supports spaces in filenames - If a file with the same name exists, append a number: `Note.md` → `Note 1.md` - Filenames become the note title in the sidebar if no frontmatter `title` is set ## Supported File Types Octarine recognizes these extensions in the workspace: **Notes:** - `.md` — Markdown notes (primary format) **Media (always recognized):** - `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp` — Images - `.mp4`, `.webm`, `.mov` — Videos **External files (default set, users can add more in settings):** - `.pdf`, `.txt`, `.docx`, `.xlsx`, `.html`, `.json`, `.csv` ## What NOT to Do - **DO NOT** modify anything in `.octarine/` — this is Octarine's internal config - **Avoid** creating custom dot-prefixed folders unless the user has enabled "Show dot-folders" in their workspace settings - **DO NOT** write non-markdown files to the root or note folders — they won't be indexed - **DO NOT** use `node_modules` or `.git` as folder names — they are ignored ## Quick Reference: Common Operations | Operation | How | |-----------|-----| | Create a note | Write a `.md` file to the workspace | | Update a note | Overwrite the existing `.md` file | | Delete a note | Delete the `.md` file from disk | | Create a folder | Create a directory in the workspace | | Add a daily note | Write to `Daily/YYYY-MM-DD.md` | | Add an image | Save to `.attachments/` and reference with `[[image.png\|500]]` | | Add tags | Include `#tag` in the note body | | Add links | Use `[[Note Name]]` wiki-link syntax | | Add tasks | Use `- [ ] task` or `- [x] done` checkboxes | | Set metadata | Add YAML frontmatter between `---` delimiters | | Add a callout | Use `> [!INFO]` blockquote syntax | | Add block math | Wrap LaTeX in `$$` on separate lines | | Add inline math | Wrap LaTeX in single `$` | | Colored text | Use `~🔴text~` with a color emoji | | Highlight text | Use `==🟡text==` with a color emoji | | Underline text | Use `~text~` (single tilde, no emoji) | | Add a diagram | Use a `mermaid` code block | | Resize an image | Use `[[image.png\|400]]` (width in pixels) | ## Full Example: Note Using All Features ```markdown --- title: Octarine Feature Showcase date: 2025-01-15 status: published --- # Octarine Feature Showcase A note demonstrating every supported syntax. #demo #showcase ## Text Formatting This has **bold**, *italic*, ~~strikethrough~~, and ~underlined~ text. ~🔴This is red text~ and ~🔵this is blue text~. ==🟡This is yellow highlighted== and ==🟢this is green highlighted==. ## Links and References See [[Related Note]] and [[Projects/Roadmap]] for more context. ## Math The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ inline. Block math: $$ \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} $$ ## Callouts > [!TIP] > Use callouts to highlight important information. > [!WARNING] > This syntax must start with `> [!TYPE]` on its own line. ## Tasks - [ ] Incomplete task - [x] Completed task ## Code ```python def hello(): print("Hello from Octarine!") ``` ## Diagram ```mermaid flowchart LR A[Input] --> B[Process] --> C[Output] ``` ## Table | Feature | Syntax | |---------|--------| | Bold | `**text**` | | Colored | `~🔴text~` | ## Media [[screenshot.png|600]] ``` Octarine will automatically: - Detect the new file via filesystem watcher - Extract and index all `#tags` - Parse `[[wiki links]]` - Count tasks (1 incomplete, 1 complete) - Parse the YAML frontmatter - Render math with KaTeX - Render mermaid diagrams - Apply colored text and highlights - Calculate word count and reading time - Display the note in the sidebar