diff --git a/skills/obsidian-sorter/SKILL.md b/skills/obsidian-sorter/SKILL.md new file mode 100644 index 0000000..1aba433 --- /dev/null +++ b/skills/obsidian-sorter/SKILL.md @@ -0,0 +1,149 @@ +--- +name: obsidian-sorter +description: File notes into Sam's Obsidian vault. Use when adding, capturing, or organizing notes in Obsidian; when asked "sort my inbox", "add this to my notes", "where does this go", or when a thought/idea/plan should be recorded. Handles the proposal-and-approve workflow where the vault owner ticks a checkbox before anything moves. +--- + +# Obsidian Sorter + +Files notes into Sam's Obsidian vault at `~/obsidian` **on host `.27`**. + +**Nothing is ever filed without the owner's approval.** You write a note into +the inbox; a watcher writes a *proposal* into the note's frontmatter; Sam ticks +`approved: true` in Obsidian; the watcher files it. + +## Where things live + +| Thing | Location | +|-------|----------| +| Vault | `.27` → `~/obsidian` (synced to Gitea `sam/obsidian-vault`) | +| Sorter code | `.27` → `~/obsidian-sorter/` | +| Watcher service | `.27` → `systemctl --user obsidian-sorter` (always running, 10s poll) | +| Command | `.27` → `~/bin/obsidian-sort` | +| Sort log | `.27` → `~/obsidian/010 inbox/_sort log.md` | + +The sorter runs **on `.27`** because that is where the vault lives. From another +machine, reach it over SSH: + +```bash +ssh sam@192.168.20.27 'obsidian-sort scan' +``` + +## The taxonomy — type mirrors folder + +Refer to the existing folder listing to see subfolders — this table is the +reference for the pattern. + +| Folder | Type | Meaning | +|--------|------|---------| +| `200 projects/` | `project` | Work in progress — something being built | +| `300 areas/` | `area` | Ongoing interest with documentation and notes | +| `400 Personal Family/` | `family` | Family / strictly non-work | +| `100 Table of Contents/` | `index` | Navigation notes only | +| `000 daily/` | `daily` | Chronological daily notes | +| `500 archive/` | `archive` | Inactive material | +| `Clippings/` | `clipping` | Browser-extension captures | +| `010 inbox/` | `note` | Unsorted placeholder | + +**A note's `type` always equals its folder.** Never invent a type. These are +**retired** and must not be used: `subject`, `tool`, `container`, `machine`, +`backup-system`, `website`, `service`, `storage`, `network-component`, `person`. + +### The lifecycle + +``` +IDEA (not started) -> 200 projects/260 Ideas to Build Create Make +BEING BUILT -> 200 projects/250 Electronics +FINISHED -> 300 areas/... +``` + +## Adding a note + +Write it into `010 inbox/` on `.27` using the generic template. **Do not choose +a folder or a type** — the sorter decides. + +```yaml +--- +created: YYYY-MM-DD HH:MM +type: note +tags: [] +aliases: [] +--- +# [[Note Title]] + +A paragraph or two describing what this actually is. The more clearly you +describe it, the better it files. +``` + +Write it via SSH, e.g.: + +```bash +ssh sam@192.168.20.27 'cat > "$HOME/obsidian/010 inbox/My Note.md"' << 'MD' +--- +created: 2026-01-01 12:00 +type: note +tags: [] +aliases: [] +--- +# [[My Note]] + +The content. +MD +``` + +Within ~10 seconds the watcher adds a proposal: + +```yaml +proposed_folder: 200 projects/250 Electronics +proposed_toc: 100 Table of Contents/Projects.md → Ideas +proposed_tags: [electronics, bluetooth] +confidence: 0.87 +approved: false +``` + +## Triggering a check + +The watcher polls every 10 seconds, so normally you do nothing. To force it: + +```bash +ssh sam@192.168.20.27 'obsidian-sort watch --once' # one pass +ssh sam@192.168.20.27 'obsidian-sort' # dry run: show plans +ssh sam@192.168.20.27 'obsidian-sort apply' # file (prompts) +ssh sam@192.168.20.27 'obsidian-sort apply --yes' # file, no prompt +ssh sam@192.168.20.27 'obsidian-sort scan' # vault summary +``` + +## Steering the sorter + +**Sam's own tags always win.** Tag a note and the sorter obeys: + +| Tag on the note | Effect | +|-----------------|--------| +| `project` | constrained to the `200 projects/` bucket | +| `family` / `personal` | constrained to `400 Personal Family/` | +| `business-idea` | pinned to `400 Personal Family/410 Business Ideas` | +| `recipe` | pinned to `400 Personal Family/450 Recipes` | + +Tag pinning costs **$0** — no model call is made. + +## Rules + +- **Never** set `type` to anything other than `note` when adding to the inbox. +- **Never** move notes into folders yourself — that is the sorter's job. +- **Never** modify `proposed_*` or `approved` fields. That is Sam's decision. +- **Never** touch `.trash/`. +- Files starting with `_` in the inbox are internal (the sort log) — ignore them. +- If asked where something belongs, use `propose` rather than guessing: + +```bash +ssh sam@192.168.20.27 'obsidian-sort propose "010 inbox/My Note.md" --jev' +``` + +## Troubleshooting + +```bash +ssh sam@192.168.20.27 'systemctl --user status obsidian-sorter' +ssh sam@192.168.20.27 'journalctl --user -u obsidian-sorter -n 50' +ssh sam@192.168.20.27 'cat "$HOME/obsidian/010 inbox/_sort log.md" | tail -30' +``` + +If the service is stopped: `systemctl --user start obsidian-sorter`. diff --git a/skills/project-docs/SKILL.md b/skills/project-docs/SKILL.md index 701d742..3559b83 100644 --- a/skills/project-docs/SKILL.md +++ b/skills/project-docs/SKILL.md @@ -23,7 +23,7 @@ When invoked, `project-docs` coordinates five documentation layers: | Platform | Target Audience | Purpose & Tone | Generated / Updated Artifacts | | :--- | :--- | :--- | :--- | | **Gitea** | Developers / Resume | Technical documentation & repository README. **Standard concise markdown**. Highlights tech stack, usage, and key tools/skills demonstrated for employment. | `/README.md` (embedded Mermaid diagram, Archify links, setup/usage guide). | -| **Obsidian** | Humans / Hiring Managers | **Human understanding**. Simple, clear, layperson-friendly language, brief. Highlights skills, tools, and concepts that showcase for employment while forming a usable tool for understanding things. | `/Projects/.md` (simple overview, employment highlights, embedded Mermaid). | +| **Obsidian** | Humans / Hiring Managers | **Human understanding**. Simple, clear, layperson-friendly language, brief. Highlights skills, tools, and concepts that showcase for employment while forming a usable tool for understanding things. | A note written into `010 inbox/` on host **`.27`** (simple overview, employment highlights, embedded Mermaid). The **`obsidian-sorter`** skill files it into `200 projects//` and updates the Table of Contents. | | **Mermaid + Archify** | Architectural Visualization | High-level system architecture and interactive HTML maps. | 1. `/docs/.mmd`
2. `/docs/diagrams/.png` (rendered via `mmdc`)
3. `/docs/-map.html` (rendered via Archify)
4. Published to `https://maps.lab.audasmedia.com.au//docs/`. | | **Vikunja** | Humans | **High-level task tracking**. Simple, brief, actionable human steps (milestones, key deliverables). | Vikunja project board or `/docs/vikunja-tasks.json`. | | **Outline** | AI Agents | **Deep AI context & document index**. Itemizes what is in each document in the collection so AI agents can inject specific files directly without searching. **Strictly uses `ste-writing` skill rules** (Simplified Technical English). | `/docs/outline/` collection (`00-index.md`, `01-system-overview.md`, `02-config-and-env.md`, `03-code-map.md`, `04-agent-runbook.md`). | @@ -45,7 +45,10 @@ Scans git commits, file edits, or structural changes, then updates affected docu For every project, step through the 5 platforms and **ask/confirm** before writing: 1. **Gitea**: *"Does a Gitea repository exist for this project, or should it be created? [Repo Name]"* -2. **Obsidian**: *"Should an Obsidian project note be created for human understanding and portfolio showcase? [Confirm / Vault Location / Note Name]"* +2. **Obsidian**: *"Should an Obsidian project note be created for human understanding and portfolio showcase? [Confirm / Note Name]"* + - Write it to `~/obsidian/010 inbox/` **on `.27`** using the note template. + - **Do not choose a folder or a type.** The `obsidian-sorter` skill proposes the + destination and the vault owner approves it. See the `obsidian-sorter` skill. 3. **Mermaid & Archify**: *"Do you want a Mermaid architecture diagram and Archify interactive map for this project? [Confirm / Topic Name]"* 4. **Vikunja**: *"Should a Vikunja project/board be created for human task tracking? [Confirm / Board Name]"* 5. **Outline**: *"Should an Outline document collection be created for AI agents to resume context across restarts? [Confirm / Collection Name]"* diff --git a/skills/project-docs/templates/obsidian-note.md.tpl b/skills/project-docs/templates/obsidian-note.md.tpl index a400d12..464801d 100644 --- a/skills/project-docs/templates/obsidian-note.md.tpl +++ b/skills/project-docs/templates/obsidian-note.md.tpl @@ -1,4 +1,7 @@ --- +title: "{{PROJECT_NAME}}" +type: note +status: active tags: - project - {{PROJECT_TAG}} @@ -7,14 +10,18 @@ skills: - {{DEMONSTRATED_SKILLS_LIST}} tools: - {{TOOLS_USED_LIST}} +aliases: [] +created: {{DATE}} --- # {{PROJECT_NAME}} — Overview ## 💡 What is this project? + {{HUMAN_EXPLANATION_SIMPLE}} ## 🌟 Key Highlights (Portfolio & Employment) + - **Concept**: {{KEY_CONCEPT}} - **Tools & Skills Showcase**: {{SHOWCASE_HIGHLIGHTS}} - **Practical Value**: {{PRACTICAL_VALUE}} @@ -26,6 +33,16 @@ tools: ``` ## 🔗 Related Notes & Links + - Gitea Repo: `{{GITEA_REPO_URL}}` - Interactive Map: [Archify Map](https://maps.lab.audasmedia.com.au/{{PROJECT_NAME}}/) - AI Context (Outline): `{{OUTLINE_DOC_URL}}` + +