From 392ae7bbe398c91a0cf7d06fa1380fe1aea6eb2f Mon Sep 17 00:00:00 2001 From: jason Date: Thu, 4 Jun 2026 16:20:56 -0500 Subject: [PATCH] first push --- .env.example | 5 + .source-references/goldbrain-memory.plugin | Bin 0 -> 14316 bytes .../.claude-plugin/plugin.json | 9 + .source-references/goldbrain-memory/README.md | 59 +++++ .../skills/goldbrain-memory/SKILL.md | 233 +++++++++++++++++ .../references/api-reference.md | 207 +++++++++++++++ .../goldbrain-memory/references/bootstrap.md | 37 +++ .../references/session-log-template.md | 108 ++++++++ .../references/vault-layout.md | 146 +++++++++++ ...n (goldbrain) rest api key and address.txt | 3 + .../obsidian rest api documentation.txt | 1 + .../references-only/reference vault/README.md | 25 ++ ...6-05-19-cpas-backdated-snapshot-refresh.md | 44 ++++ ...26-05-27-cpas-rolloff-clean-cycle-model.md | 37 +++ ...5-28-file-obsidian-heading-resolver-bug.md | 152 +++++++++++ .../reference vault/memory/inbox.md | 13 + .../memory/people/bryan-gilliom.md | 17 ++ .../memory/people/mitch-tankersley.md | 130 ++++++++++ .../reference vault/memory/profile.md | 85 ++++++ .../reference vault/memory/projects/agents.md | 77 ++++++ .../reference vault/memory/projects/alwisp.md | 77 ++++++ .../reference vault/memory/projects/breedr.md | 75 ++++++ .../memory/projects/codedump.md | 84 ++++++ .../memory/projects/codexium-odoo.md | 56 ++++ .../reference vault/memory/projects/cpas.md | 96 +++++++ .../reference vault/memory/projects/email.md | 74 ++++++ .../memory/projects/fabdash.md | 79 ++++++ .../memory/projects/family-planner.md | 82 ++++++ .../reference vault/memory/projects/inven.md | 82 ++++++ .../reference vault/memory/projects/memer.md | 79 ++++++ .../memory/projects/mempalace.md | 65 +++++ .../memory/projects/mrp-qrcode.md | 52 ++++ .../reference vault/memory/projects/mrp.md | 56 ++++ .../memory/projects/nyaa-crawler.md | 96 +++++++ .../memory/projects/obsidian-memory-plugin.md | 128 +++++++++ .../reference vault/memory/projects/pnger.md | 82 ++++++ .../reference vault/memory/projects/pos.md | 115 ++++++++ .../reference vault/memory/projects/qrknit.md | 57 ++++ .../memory/projects/rack-planner.md | 78 ++++++ .../memory/projects/stepview.md | 87 +++++++ .../memory/projects/storybid.md | 95 +++++++ .../memory/projects/totalmcp.md | 88 +++++++ .../memory/projects/ui-tracker.md | 87 +++++++ .../memory/projects/unifi-access-dashboard.md | 118 +++++++++ .../memory/projects/unraid-deployment.md | 86 ++++++ .../reference vault/memory/projects/wfh.md | 76 ++++++ .../2026-05-27-cpas-authentication.md | 54 ++++ .../2026-05-27-gitea-repo-descriptions.md | 34 +++ ...2026-05-27-obsidian-memory-plugin-build.md | 38 +++ .../2026-05-27-personal-gitea-plugin.md | 29 +++ .../2026-05-28-uad-filter-and-merge.md | 58 +++++ ...-05-28-unifi-dashboard-multi-controller.md | 37 +++ .../reference-obsidian-memory.plugin | Bin 0 -> 11385 bytes BOOTSTRAP.md | 192 ++++++++++++++ CLAUDE.md | 50 ++++ README.md | 20 ++ STRUCTURE.md | 66 +++++ _agent/context/current-context.md | 45 ++++ _agent/heartbeat/README.md | 3 + _agent/memory/episodic/README.md | 5 + .../memory/semantic/operator-preferences.md | 34 +++ _agent/memory/working/active-setup.md | 30 +++ _agent/outputs/briefs/README.md | 5 + _agent/outputs/drafts/README.md | 5 + _agent/outputs/summaries/README.md | 5 + _agent/outputs/synthesis/README.md | 5 + .../2026-06-01-2200-initial-vault-scaffold.md | 53 ++++ .../2026-06-02-1618-goldbrain-plugin-build.md | 58 +++++ _agent/skills/active/README.md | 3 + _agent/skills/archived/README.md | 5 + _agent/templates/context-bundle-template.md | 27 ++ _agent/templates/semantic-memory-template.md | 23 ++ _agent/templates/session-log-template.md | 29 +++ _agent/templates/working-memory-template.md | 22 ++ archive/README.md | 3 + archive/imports/README.md | 5 + archive/notes/README.md | 5 + archive/projects/README.md | 5 + areas/business/business-ops.md | 22 ++ areas/learning/learning-backlog.md | 22 ++ areas/personal/README.md | 5 + areas/systems/systems-architecture.md | 23 ++ decisions/by-date/README.md | 5 + decisions/by-project/README.md | 5 + decisions/decision-template.md | 25 ++ inbox/captures/README.md | 3 + inbox/imports/README.md | 5 + inbox/processing-log/README.md | 5 + index.md | 28 ++ journal/daily/2026-06-01.md | 37 +++ journal/daily/2026-06-02.md | 27 ++ journal/monthly/README.md | 5 + journal/templates/daily-note-template.md | 25 ++ journal/templates/weekly-review-template.md | 26 ++ journal/weekly/README.md | 5 + projects/active/vault-foundation.md | 54 ++++ projects/archived/README.md | 5 + projects/incubating/README.md | 5 + projects/on-hold/README.md | 5 + projects/project-template.md | 31 +++ resources/concepts/agent-memory-model.md | 32 +++ resources/meetings/README.md | 5 + resources/people/bryan-gilliom.md | 42 +++ resources/people/jason-stedwell.md | 38 +++ .../references/obsidian-local-rest-api.md | 245 ++++++++++++++++++ resources/source-material/README.md | 5 + reviews/annual/README.md | 5 + reviews/monthly/README.md | 5 + reviews/quarterly/README.md | 5 + reviews/weekly/2026-W23.md | 37 +++ spinup.md | 29 +++ 111 files changed, 5312 insertions(+) create mode 100644 .env.example create mode 100644 .source-references/goldbrain-memory.plugin create mode 100644 .source-references/goldbrain-memory/.claude-plugin/plugin.json create mode 100644 .source-references/goldbrain-memory/README.md create mode 100644 .source-references/goldbrain-memory/skills/goldbrain-memory/SKILL.md create mode 100644 .source-references/goldbrain-memory/skills/goldbrain-memory/references/api-reference.md create mode 100644 .source-references/goldbrain-memory/skills/goldbrain-memory/references/bootstrap.md create mode 100644 .source-references/goldbrain-memory/skills/goldbrain-memory/references/session-log-template.md create mode 100644 .source-references/goldbrain-memory/skills/goldbrain-memory/references/vault-layout.md create mode 100644 .source-references/references-only/obsidian (goldbrain) rest api key and address.txt create mode 100644 .source-references/references-only/obsidian rest api documentation.txt create mode 100644 .source-references/references-only/reference vault/README.md create mode 100644 .source-references/references-only/reference vault/memory/decisions/2026-05-19-cpas-backdated-snapshot-refresh.md create mode 100644 .source-references/references-only/reference vault/memory/decisions/2026-05-27-cpas-rolloff-clean-cycle-model.md create mode 100644 .source-references/references-only/reference vault/memory/decisions/2026-05-28-file-obsidian-heading-resolver-bug.md create mode 100644 .source-references/references-only/reference vault/memory/inbox.md create mode 100644 .source-references/references-only/reference vault/memory/people/bryan-gilliom.md create mode 100644 .source-references/references-only/reference vault/memory/people/mitch-tankersley.md create mode 100644 .source-references/references-only/reference vault/memory/profile.md create mode 100644 .source-references/references-only/reference vault/memory/projects/agents.md create mode 100644 .source-references/references-only/reference vault/memory/projects/alwisp.md create mode 100644 .source-references/references-only/reference vault/memory/projects/breedr.md create mode 100644 .source-references/references-only/reference vault/memory/projects/codedump.md create mode 100644 .source-references/references-only/reference vault/memory/projects/codexium-odoo.md create mode 100644 .source-references/references-only/reference vault/memory/projects/cpas.md create mode 100644 .source-references/references-only/reference vault/memory/projects/email.md create mode 100644 .source-references/references-only/reference vault/memory/projects/fabdash.md create mode 100644 .source-references/references-only/reference vault/memory/projects/family-planner.md create mode 100644 .source-references/references-only/reference vault/memory/projects/inven.md create mode 100644 .source-references/references-only/reference vault/memory/projects/memer.md create mode 100644 .source-references/references-only/reference vault/memory/projects/mempalace.md create mode 100644 .source-references/references-only/reference vault/memory/projects/mrp-qrcode.md create mode 100644 .source-references/references-only/reference vault/memory/projects/mrp.md create mode 100644 .source-references/references-only/reference vault/memory/projects/nyaa-crawler.md create mode 100644 .source-references/references-only/reference vault/memory/projects/obsidian-memory-plugin.md create mode 100644 .source-references/references-only/reference vault/memory/projects/pnger.md create mode 100644 .source-references/references-only/reference vault/memory/projects/pos.md create mode 100644 .source-references/references-only/reference vault/memory/projects/qrknit.md create mode 100644 .source-references/references-only/reference vault/memory/projects/rack-planner.md create mode 100644 .source-references/references-only/reference vault/memory/projects/stepview.md create mode 100644 .source-references/references-only/reference vault/memory/projects/storybid.md create mode 100644 .source-references/references-only/reference vault/memory/projects/totalmcp.md create mode 100644 .source-references/references-only/reference vault/memory/projects/ui-tracker.md create mode 100644 .source-references/references-only/reference vault/memory/projects/unifi-access-dashboard.md create mode 100644 .source-references/references-only/reference vault/memory/projects/unraid-deployment.md create mode 100644 .source-references/references-only/reference vault/memory/projects/wfh.md create mode 100644 .source-references/references-only/reference vault/memory/sessions/2026-05-27-cpas-authentication.md create mode 100644 .source-references/references-only/reference vault/memory/sessions/2026-05-27-gitea-repo-descriptions.md create mode 100644 .source-references/references-only/reference vault/memory/sessions/2026-05-27-obsidian-memory-plugin-build.md create mode 100644 .source-references/references-only/reference vault/memory/sessions/2026-05-27-personal-gitea-plugin.md create mode 100644 .source-references/references-only/reference vault/memory/sessions/2026-05-28-uad-filter-and-merge.md create mode 100644 .source-references/references-only/reference vault/memory/sessions/2026-05-28-unifi-dashboard-multi-controller.md create mode 100644 .source-references/references-only/reference-obsidian-memory.plugin create mode 100644 BOOTSTRAP.md create mode 100644 CLAUDE.md create mode 100644 STRUCTURE.md create mode 100644 _agent/context/current-context.md create mode 100644 _agent/heartbeat/README.md create mode 100644 _agent/memory/episodic/README.md create mode 100644 _agent/memory/semantic/operator-preferences.md create mode 100644 _agent/memory/working/active-setup.md create mode 100644 _agent/outputs/briefs/README.md create mode 100644 _agent/outputs/drafts/README.md create mode 100644 _agent/outputs/summaries/README.md create mode 100644 _agent/outputs/synthesis/README.md create mode 100644 _agent/sessions/2026-06-01-2200-initial-vault-scaffold.md create mode 100644 _agent/sessions/2026-06-02-1618-goldbrain-plugin-build.md create mode 100644 _agent/skills/active/README.md create mode 100644 _agent/skills/archived/README.md create mode 100644 _agent/templates/context-bundle-template.md create mode 100644 _agent/templates/semantic-memory-template.md create mode 100644 _agent/templates/session-log-template.md create mode 100644 _agent/templates/working-memory-template.md create mode 100644 archive/README.md create mode 100644 archive/imports/README.md create mode 100644 archive/notes/README.md create mode 100644 archive/projects/README.md create mode 100644 areas/business/business-ops.md create mode 100644 areas/learning/learning-backlog.md create mode 100644 areas/personal/README.md create mode 100644 areas/systems/systems-architecture.md create mode 100644 decisions/by-date/README.md create mode 100644 decisions/by-project/README.md create mode 100644 decisions/decision-template.md create mode 100644 inbox/captures/README.md create mode 100644 inbox/imports/README.md create mode 100644 inbox/processing-log/README.md create mode 100644 index.md create mode 100644 journal/daily/2026-06-01.md create mode 100644 journal/daily/2026-06-02.md create mode 100644 journal/monthly/README.md create mode 100644 journal/templates/daily-note-template.md create mode 100644 journal/templates/weekly-review-template.md create mode 100644 journal/weekly/README.md create mode 100644 projects/active/vault-foundation.md create mode 100644 projects/archived/README.md create mode 100644 projects/incubating/README.md create mode 100644 projects/on-hold/README.md create mode 100644 projects/project-template.md create mode 100644 resources/concepts/agent-memory-model.md create mode 100644 resources/meetings/README.md create mode 100644 resources/people/bryan-gilliom.md create mode 100644 resources/people/jason-stedwell.md create mode 100644 resources/references/obsidian-local-rest-api.md create mode 100644 resources/source-material/README.md create mode 100644 reviews/annual/README.md create mode 100644 reviews/monthly/README.md create mode 100644 reviews/quarterly/README.md create mode 100644 reviews/weekly/2026-W23.md create mode 100644 spinup.md diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..e0eba2c --- /dev/null +++ b/.env.example @@ -0,0 +1,5 @@ +# Copy to your local shell env or secret manager. Do not commit real secrets into the vault. +OBSIDIAN_REST_API_URL=https://goldbrainapi.mpm.to +OBSIDIAN_REST_API_KEY=replace-me +OBSIDIAN_VAULT_NAME=goldbrain +COWORK_PLUGIN_MODE=disabled diff --git a/.source-references/goldbrain-memory.plugin b/.source-references/goldbrain-memory.plugin new file mode 100644 index 0000000000000000000000000000000000000000..5d11de58b4a33c12e972f455b5bb86df4a237145 GIT binary patch literal 14316 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.md + ├── templates/ ← canonical note templates + ├── outputs/ ← briefs / drafts / summaries / synthesis + ├── skills/ ← active / archived + └── heartbeat/ +``` + +## First run + +The vault ships its own `BOOTSTRAP.md`. On first use the skill reads `/vault/BOOTSTRAP.md`; if present it follows that preflight, and if absent (a fresh empty vault) it offers to bootstrap. + +## Skills + +| Skill | Triggers | +|-------|----------| +| `goldbrain-memory` | "remember that", "save to memory", "what do you know about me", "load my profile", "check my notes", "log this decision", "add to my inbox" — and proactively at the start of substantive conversations | + +## Requirements + +- Obsidian running on the backend with the [Local REST API plugin](https://github.com/coddingtonbear/obsidian-local-rest-api) enabled (binding host `0.0.0.0`) +- HTTPS access to `https://goldbrainapi.mpm.to` from the Claude/CoWork session environment diff --git a/.source-references/goldbrain-memory/skills/goldbrain-memory/SKILL.md b/.source-references/goldbrain-memory/skills/goldbrain-memory/SKILL.md new file mode 100644 index 0000000..02d8580 --- /dev/null +++ b/.source-references/goldbrain-memory/skills/goldbrain-memory/SKILL.md @@ -0,0 +1,233 @@ +--- +name: goldbrain-memory +description: Use the goldbrain Obsidian vault as persistent memory across Claude/CoWork sessions. Triggers when the operator says "remember that", "remember this", "save to memory", "what do you know about me", "load my memory", "load my profile", "what did we discuss before", "check my notes", "what's my context", "what are my preferences", "log this decision", "add to my inbox", or starts a new project that should be tracked. Also triggers proactively at the start of substantive conversations to load operator context, and at the end to log session outcomes. +--- + +# Goldbrain Memory + +Use the **goldbrain** Obsidian vault as persistent memory. Read context accumulated across sessions; write things the operator asks to be remembered. + +The primary operator is **Bryan Gilliom** (CEO, Message Point Media). Unless stated otherwise, "the operator" means Bryan. Jason is the vault's architect, not the day-to-day user. Write memory in third person ("Bryan prefers X", not "I prefer X"). + +## API Configuration + +All calls use these constants — hardcoded for this personal plugin: + +``` +OBSIDIAN_BASE = https://goldbrainapi.mpm.to +OBSIDIAN_KEY = fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8 +``` + +The endpoint has a **valid TLS certificate**, so `-k` is not needed (add it only if the cert ever changes to self-signed). Always pass the `Authorization: Bearer` header. Paths address the vault **at its root** (e.g. `/vault/_agent/...`). + +Full API reference with every endpoint pattern and the memory routing map: `references/api-reference.md`. Vault layout and frontmatter conventions: `references/vault-layout.md`. + +## When to Load Memory + +Load at the start of any substantive conversation — anything beyond a single quick factual question. The signal: the operator is starting work, planning, asking for help with something that has state, or referencing prior discussions. + +Do NOT narrate this loading. Reading memory is expected behavior. + +### Loading procedure + +**Step 1 — Confirm the vault is bootstrapped:** + +```bash +curl -s \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + "https://goldbrainapi.mpm.to/vault/BOOTSTRAP.md" +``` + +If this returns 404, the vault is not set up. Follow `references/bootstrap.md` before doing anything else. + +**Step 2 — Read operator preferences (the profile):** + +```bash +curl -s \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + "https://goldbrainapi.mpm.to/vault/_agent/memory/semantic/operator-preferences.md" +``` + +**Step 3 — Read active context and the latest session:** + +```bash +# Current task-scoped context bundle +curl -s -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + "https://goldbrainapi.mpm.to/vault/_agent/context/current-context.md" + +# List recent session logs, then read the most relevant +curl -s -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + "https://goldbrainapi.mpm.to/vault/_agent/sessions/" +``` + +**Step 4 — If a specific project is in play, list active projects and read the best match:** + +```bash +curl -s -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + "https://goldbrainapi.mpm.to/vault/projects/active/" + +curl -s -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + "https://goldbrainapi.mpm.to/vault/projects/active/.md" +``` + +Optionally read today's daily note at `/vault/journal/daily/YYYY-MM-DD.md` for current priorities and open loops. + +## When to Write Memory + +Write when the operator: + +- States a fact, preference, or commitment worth keeping ("I prefer X", "we use uv not pip", "standup is Tuesday at 10") +- Makes a non-obvious decision worth recording +- Says "remember that", "save this", "log this", "add to memory", "note that" +- Finishes a meaningful working session future sessions should pick up + +Write in third person about Bryan. Every note carries the canonical frontmatter (see below). Agent-generated notes set `agent_written: true`. + +### Append to a file (default — additive entries) + +Write content to a temp file first to handle multi-line markdown cleanly, then POST: + +```bash +cat > /tmp/obs_entry.md << 'OBSEOF' +- 2026-06-02: +OBSEOF + +curl -s -X POST \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + -H "Content-Type: text/markdown" \ + --data-binary @/tmp/obs_entry.md \ + "https://goldbrainapi.mpm.to/vault/inbox/captures/inbox.md" +``` + +POST appends to the end of a file (creating it if absent). Use it for inbox captures, log sections, and daily-note Agent Log entries. + +### Patch a specific heading (targeted update) + +**Heading targets use the FULL heading path, `::`-delimited from the top-level heading** — a bare subheading name fails with `invalid-target`. For example, `## Fact / Pattern` under the `# Operator Preferences` H1 is targeted as `Operator Preferences::Fact / Pattern`. When unsure of the exact path, read the document map first (see below). + +```bash +cat > /tmp/obs_patch.md << 'OBSEOF' +Bryan prefers status updates that lead with the decision. +OBSEOF + +curl -s -X PATCH \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + -H "Operation: append" \ + -H "Target-Type: heading" \ + -H "Target: Operator Preferences::Fact / Pattern" \ + -H "Content-Type: text/markdown" \ + --data-binary @/tmp/obs_patch.md \ + "https://goldbrainapi.mpm.to/vault/_agent/memory/semantic/operator-preferences.md" +``` + +Use `Operation: replace` to overwrite a section entirely (e.g. a project's `Project Name::Current status`). Percent-encode non-ASCII characters in the `Target` header; spaces are fine. + +**Discover exact heading paths** when unsure — GET the note with the document-map Accept header: + +```bash +curl -s -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + -H "Accept: application/vnd.olrapi.document-map+json" \ + "https://goldbrainapi.mpm.to/vault/_agent/memory/semantic/operator-preferences.md" +``` + +It returns `{ "headings": [...], "blocks": [...], "frontmatterFields": [...] }` — copy the heading string verbatim into `Target`. + +### Create or overwrite a file (PUT) + +```bash +cat > /tmp/obs_file.md << 'OBSEOF' +--- +type: project +status: active +created: 2026-06-02 +updated: 2026-06-02 +tags: [] +agent_written: true +source_notes: [] +--- + +# Project Name + +## Current status +... + +## Related +- [[journal/daily/2026-06-02]] +OBSEOF + +curl -s -X PUT \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + -H "Content-Type: text/markdown" \ + --data-binary @/tmp/obs_file.md \ + "https://goldbrainapi.mpm.to/vault/projects/active/my-project.md" +``` + +The API creates intermediate directories automatically. + +### Search the vault + +```bash +curl -s -X POST \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + "https://goldbrainapi.mpm.to/search/simple/?query=your+search+terms" +``` + +## Where to Write + +| Situation | File / path | Method | +|-----------|-------------|--------| +| Unsure where it goes / quick capture | `_agent/.../` → use `inbox/captures/inbox.md` (date-prefixed line) | POST | +| Operator preference or durable fact | `_agent/memory/semantic/operator-preferences.md` (append under the right heading) | PATCH | +| Other durable facts / patterns | `_agent/memory/semantic/.md` | PUT | +| What happened (event record) | `_agent/memory/episodic/.md` | PUT | +| Short-lived working state | `_agent/memory/working/.md` | PUT | +| Task-scoped context / focus | `_agent/context/current-context.md` | PATCH / PUT | +| Working session ended with substance | `_agent/sessions/YYYY-MM-DD-HHMM-.md` | PUT | +| Long-running project state | `projects/active/.md` | PUT + PATCH | +| Non-obvious decision (ADR) | `decisions/by-date/YYYY-MM-DD-.md` (mirror into `by-project/`) | PUT | +| Person context | `resources/people/.md` | PUT / PATCH | +| Concept / reference note | `resources/concepts/` or `resources/references/` | PUT | +| Daily activity / Agent Log | `journal/daily/YYYY-MM-DD.md` | POST / PATCH | + +Never delete files unless the operator explicitly asks. Memory is append-friendly; deletion is destructive. + +## Session Logging + +At the end of substantive conversations (ones that produced decisions, artifacts, or commitments), create a session log. Ask once if unsure: "Want me to log a session note for this?" + +Session logs go in `_agent/sessions/YYYY-MM-DD-HHMM-.md`. See `references/session-log-template.md` for the exact format. + +```bash +cat > /tmp/obs_session.md << 'OBSEOF' + +OBSEOF + +curl -s -X PUT \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + -H "Content-Type: text/markdown" \ + --data-binary @/tmp/obs_session.md \ + "https://goldbrainapi.mpm.to/vault/_agent/sessions/2026-06-02-1430-my-session.md" +``` + +Then append a one-line entry to the daily note's **Agent Log** section. + +## Vault Unreachable + +If the API returns a connection error, timeout, or `502`, tell the operator once that the memory vault is unreachable (a `502` usually means Obsidian/the REST plugin is not running on the backend), then proceed without memory. Do not retry repeatedly. + +## Style Rules + +- Write in third person about Bryan: "Bryan prefers X", not "I prefer X". +- Do not attribute Jason's design preferences to Bryan — capture Bryan's preferences only from observed interactions. +- Every memory file has canonical YAML frontmatter — see `references/vault-layout.md`. +- Set `agent_written: true` on agent-generated notes and list `source_notes` (plain relative paths, not links). +- **Never put `[[wikilinks]]` in frontmatter** — YAML parses them as nested lists and the links break in Obsidian's reading view. Put all cross-references in a `## Related` section in the note **body** as a bulleted list of `[[links]]`. +- Use Obsidian wiki links (`[[note name]]`) freely in the note **body** for cross-references. +- Keep entries short and focused. Fewer, sharper entries beat many noisy ones. +- About to write something large or sensitive? Show the operator the content first and confirm. + +## What This Skill Does Not Do + +- Does not replace reasoning. The vault is reference material — apply judgment. +- Does not auto-summarize the whole vault. Read targeted files, not everything. +- Does not store passwords or secrets, and never writes the API key into a vault note. If asked to "remember my password is X", decline and suggest a password manager. diff --git a/.source-references/goldbrain-memory/skills/goldbrain-memory/references/api-reference.md b/.source-references/goldbrain-memory/skills/goldbrain-memory/references/api-reference.md new file mode 100644 index 0000000..f33be0d --- /dev/null +++ b/.source-references/goldbrain-memory/skills/goldbrain-memory/references/api-reference.md @@ -0,0 +1,207 @@ +# Goldbrain — Obsidian Local REST API Reference + +Server: `https://goldbrainapi.mpm.to` (reverse proxy → Obsidian Local REST API on `192.168.86.15:27124`) +Auth header: `Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8` +The endpoint has a **valid TLS certificate** — `-k` is not required. Paths address the vault at its **root**. + +--- + +## Reading Files + +```bash +# Read any file by vault path +curl -s \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + "https://goldbrainapi.mpm.to/vault/_agent/context/current-context.md" +``` + +Returns raw file content (text/markdown). On 404, the file does not exist. + +```bash +# Read a specific heading's content only +curl -s \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + "https://goldbrainapi.mpm.to/vault/_agent/memory/semantic/operator-preferences.md/heading/Operator" +``` + +Nested headings: separate levels with `::` (URL-encode spaces as `%20`): +``` +/vault/path/to/note.md/heading/Work%3A%3AMeetings +``` + +--- + +## Listing Directories + +```bash +# List contents of a directory (trailing slash required) +curl -s \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + "https://goldbrainapi.mpm.to/vault/_agent/sessions/" +``` + +Returns JSON: `{ "files": [...], "folders": [...] }`. + +--- + +## Appending Content (POST) + +`POST` appends to the **end** of an existing file. Creates the file if it doesn't exist. + +```bash +cat > /tmp/obs_entry.md << 'OBSEOF' +- 2026-06-02: your entry here +OBSEOF + +curl -s -X POST \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + -H "Content-Type: text/markdown" \ + --data-binary @/tmp/obs_entry.md \ + "https://goldbrainapi.mpm.to/vault/inbox/captures/inbox.md" +``` + +--- + +## Creating or Overwriting Files (PUT) + +`PUT` creates a new file or fully overwrites an existing one. Intermediate directories are created automatically. + +```bash +cat > /tmp/obs_file.md << 'OBSEOF' +--- +type: session-log +status: complete +created: 2026-06-02 +updated: 2026-06-02 +tags: [agent, session] +agent_written: true +source_notes: [] +--- + +# content here + +## Related +- [[projects/active/some-project]] +OBSEOF + +curl -s -X PUT \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + -H "Content-Type: text/markdown" \ + --data-binary @/tmp/obs_file.md \ + "https://goldbrainapi.mpm.to/vault/_agent/sessions/2026-06-02-1430-my-session.md" +``` + +--- + +## Patching a Specific Section (PATCH) + +`PATCH` edits inside a file without rewriting it. Target and operation are set via headers. + +### Append under a heading + +**Heading targets must be the FULL heading path, `::`-delimited from the top-level heading.** A bare subheading name returns `400 invalid-target` (errorCode 40080). Example: `## Fact / Pattern` nested under `# Operator Preferences` → `Target: Operator Preferences::Fact / Pattern`. Percent-encode non-ASCII characters (e.g. `H%C3%A9llo`); spaces are fine. + +```bash +cat > /tmp/obs_patch.md << 'OBSEOF' +Bryan prefers concise status updates — lead with the decision. +OBSEOF + +curl -s -X PATCH \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + -H "Operation: append" \ + -H "Target-Type: heading" \ + -H "Target: Operator Preferences::Fact / Pattern" \ + -H "Content-Type: text/markdown" \ + --data-binary @/tmp/obs_patch.md \ + "https://goldbrainapi.mpm.to/vault/_agent/memory/semantic/operator-preferences.md" +``` + +### Discover heading / block / frontmatter targets + +When unsure of the exact heading path, GET the note with the document-map Accept header: + +```bash +curl -s \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + -H "Accept: application/vnd.olrapi.document-map+json" \ + "https://goldbrainapi.mpm.to/vault/_agent/memory/semantic/operator-preferences.md" +``` + +Returns `{ "headings": [...], "blocks": [...], "frontmatterFields": [...] }`. Copy the heading string verbatim into `Target`. + +### Replace a heading's content entirely + +Same call with `Operation: replace` — e.g. to refresh a project's `Project Name::Current status`. + +### Prepend under a heading + +Same call with `Operation: prepend`. + +### Patch a frontmatter field + +```bash +curl -s -X PATCH \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + -H "Operation: replace" \ + -H "Target-Type: frontmatter" \ + -H "Target: updated" \ + -H "Content-Type: application/json" \ + --data '"2026-06-02"' \ + "https://goldbrainapi.mpm.to/vault/projects/active/vault-foundation.md" +``` + +--- + +## Searching + +```bash +curl -s -X POST \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + "https://goldbrainapi.mpm.to/search/simple/?query=weekly+review" +``` + +Returns an array of `{ filename, score, matches: [{ context, match }] }`. + +--- + +## Deleting Files + +```bash +curl -s -X DELETE \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + "https://goldbrainapi.mpm.to/vault/archive/notes/old-note.md" +``` + +Only on explicit operator request. Deletion is destructive. + +--- + +## URL-Encoding Notes + +- Path separators (`/`) in the vault path are **literal** — do not encode them. +- Spaces in filenames or heading targets in a URL: use `%20`. +- Nested heading levels in a URL path: use `%3A%3A` for `::`. +- Heading text in the `Target:` header: the **full heading path** joined by `::` (e.g. `Operator Preferences::Fact / Pattern`), no `#`; spaces are fine; percent-encode non-ASCII. + +--- + +## Memory Routing Map + +| Situation | Vault path | Method | +|-----------|-----------|--------| +| Quick capture / unsorted | `inbox/captures/inbox.md` (date-prefixed line) | POST | +| Raw imported material | `inbox/imports/` | PUT | +| Operator preference / durable fact | `_agent/memory/semantic/operator-preferences.md` | PATCH | +| Other durable facts, patterns | `_agent/memory/semantic/.md` | PUT | +| Event record (what happened) | `_agent/memory/episodic/.md` | PUT | +| Short-lived, time-boxed state | `_agent/memory/working/.md` | PUT | +| Task-scoped context / focus | `_agent/context/current-context.md` | PATCH / PUT | +| Working-session log | `_agent/sessions/YYYY-MM-DD-HHMM-.md` | PUT | +| Long-running project state | `projects/active/.md` | PUT + PATCH | +| Non-obvious decision (ADR) | `decisions/by-date/YYYY-MM-DD-.md` (mirror `by-project/`) | PUT | +| Person context | `resources/people/.md` | PUT / PATCH | +| Concept / reference note | `resources/concepts/` or `resources/references/` | PUT | +| Daily activity / Agent Log | `journal/daily/YYYY-MM-DD.md` | POST / PATCH | +| Periodic review | `reviews/{weekly,monthly,quarterly,annual}/` | PUT | + +**Slug rules:** kebab-case, ASCII, ~40 chars max. Every file carries canonical frontmatter (see `vault-layout.md`). diff --git a/.source-references/goldbrain-memory/skills/goldbrain-memory/references/bootstrap.md b/.source-references/goldbrain-memory/skills/goldbrain-memory/references/bootstrap.md new file mode 100644 index 0000000..0a41499 --- /dev/null +++ b/.source-references/goldbrain-memory/skills/goldbrain-memory/references/bootstrap.md @@ -0,0 +1,37 @@ +# Bootstrap Procedure + +The goldbrain vault ships its **own** `BOOTSTRAP.md` at the vault root — that file is the canonical preflight/repair manifest. This plugin defers to it rather than duplicating the logic. + +## Normal case — vault already bootstrapped + +At session start, read the in-vault manifest: + +```bash +curl -s \ + -H "Authorization: Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8" \ + "https://goldbrainapi.mpm.to/vault/BOOTSTRAP.md" +``` + +If it returns content (200), the vault is set up. Skim its preflight checklist, then read `CLAUDE.md` for the operating contract and proceed with the loading procedure in `SKILL.md`. The in-vault `BOOTSTRAP.md` describes how to repair any missing folders/files; follow it if something is absent. **Never overwrite an existing file** during repair — generate only what is missing. + +## Fresh-vault case — BOOTSTRAP.md returns 404 + +This means the REST API is pointed at an empty vault. Confirm with the operator once: + +> "The goldbrain vault looks empty — there's no `BOOTSTRAP.md`. The standard scaffold (control docs, folder tree, templates, seed notes) needs to be loaded before I can use it as memory. Want me to create the core seed files now?" + +If yes, create the minimum viable seed with `PUT` (the API creates intermediate directories automatically), then let the vault's own structure grow from there: + +1. `CLAUDE.md` — operating contract and session protocol +2. `BOOTSTRAP.md` — preflight/repair manifest +3. `STRUCTURE.md` — layout, taxonomy, frontmatter standard +4. `index.md` — navigation hub +5. `_agent/memory/semantic/operator-preferences.md` — operator profile (empty, no fabricated facts) +6. `_agent/context/current-context.md` — empty context bundle +7. `inbox/captures/inbox.md` — capture file + +Prefer copying the full prepared scaffold into the Obsidian vault folder over reconstructing it by hand — it is the source of truth for goldbrain's structure. + +## After bootstrap + +Tell the operator briefly what was created, append a line to the daily note's **Agent Log**, and write a session log in `_agent/sessions/`. Do not over-explain — they can browse the vault. diff --git a/.source-references/goldbrain-memory/skills/goldbrain-memory/references/session-log-template.md b/.source-references/goldbrain-memory/skills/goldbrain-memory/references/session-log-template.md new file mode 100644 index 0000000..fef301d --- /dev/null +++ b/.source-references/goldbrain-memory/skills/goldbrain-memory/references/session-log-template.md @@ -0,0 +1,108 @@ +# Session Log Template + +Session logs go in: `_agent/sessions/YYYY-MM-DD-HHMM-.md` + +The slug describes what the session was about in 2–5 words, kebab-case. +Examples: `2026-06-02-1430-goldbrain-plugin-build.md`, `2026-05-14-0900-q1-review-prep.md`. + +Keep logs focused. Capture the goal, what was read/done, decisions, outputs, open threads, and the next step. This matches the vault's `_agent/templates/session-log-template.md`. + +--- + +## Template + +```markdown +--- +type: session-log +status: complete +created: 2026-06-02T14:30 +updated: 2026-06-02T14:30 +tags: [agent, session] +agent_written: true +source_notes: [] +session_date: 2026-06-02 +client: claude-code +--- + +# Session Log + +## Goal +One line — what this session set out to do. + +## Notes Read +- [[note]] — why it was relevant +(omit if none) + +## Actions Taken +Brief narrative or bullets of what was done. + +## Decisions Made +- Decision — why +(omit section if none) + +## Outputs Created +- `path/or/filename` — what it is +(omit section if none) + +## Open Threads +- [ ] unresolved question or next step +(omit section if none) + +## Suggested Next Step +One sentence: what to do first next time on this topic. + +## Related +- [[wikilinks go here, in the body — never in frontmatter]] +``` + +--- + +## Example + +```markdown +--- +type: session-log +status: complete +created: 2026-06-02T14:30 +updated: 2026-06-02T14:30 +tags: [agent, session, plugin] +agent_written: true +source_notes: ["resources/references/obsidian-local-rest-api.md"] +session_date: 2026-06-02 +client: claude-code +--- + +# Session Log + +## Goal +Build and package the goldbrain-memory CoWork plugin against the live vault. + +## Notes Read +- [[BOOTSTRAP]], [[STRUCTURE]], [[_agent/memory/semantic/operator-preferences]] + +## Actions Taken +Verified the REST API end-to-end, confirmed the scaffold copied into the live vault, +created missing empty folders, and built the plugin (SKILL + 4 reference files). + +## Decisions Made +- Vault addressed at root (no `Projects/agents/` prefix) — goldbrain is a dedicated vault. +- Key hardcoded in the plugin (not in the vault) — personal plugin, per the reference pattern. + +## Outputs Created +- `goldbrain-memory.plugin` — installable CoWork plugin + +## Open Threads +- [ ] Validate Claude Code direct filesystem access to the vault host. + +## Suggested Next Step +Install the plugin and run a live load/write through it to confirm the skill triggers. + +## Related +- [[projects/active/vault-foundation]] +- [[resources/references/obsidian-local-rest-api]] +``` + +After writing the log, append a one-line entry to the daily note's **Agent Log** section. + +> **Reminder:** wiki links go in the body (e.g. this `## Related` section), never in YAML +> frontmatter. `source_notes` in frontmatter holds plain relative path strings, not `[[links]]`. diff --git a/.source-references/goldbrain-memory/skills/goldbrain-memory/references/vault-layout.md b/.source-references/goldbrain-memory/skills/goldbrain-memory/references/vault-layout.md new file mode 100644 index 0000000..87f8739 --- /dev/null +++ b/.source-references/goldbrain-memory/skills/goldbrain-memory/references/vault-layout.md @@ -0,0 +1,146 @@ +# Vault Layout & Frontmatter Conventions + +Mirrors the canonical conventions defined in the vault's own `STRUCTURE.md` and `BOOTSTRAP.md`. If those change, they are the source of truth. + +## Folder Map (root-addressed) + +``` +/vault/ +├── CLAUDE.md ← operating contract + session protocol +├── STRUCTURE.md ← layout, taxonomy, frontmatter standard +├── BOOTSTRAP.md ← preflight/repair manifest (read first) +├── spinup.md index.md README.md +├── inbox/ +│ ├── captures/ ← quick captures (inbox.md), date-prefixed lines +│ ├── imports/ ← raw imported material +│ └── processing-log/ +├── journal/ +│ ├── daily/ ← YYYY-MM-DD.md (has an "Agent Log" section) +│ ├── weekly/ monthly/ +│ └── templates/ +├── projects/ +│ ├── active/ ← .md, long-running project state +│ ├── incubating/ on-hold/ archived/ +│ └── project-template.md +├── areas/ ← business / personal / learning / systems +├── resources/ +│ ├── concepts/ references/ meetings/ source-material/ +│ └── people/ ← .md +├── decisions/ +│ ├── by-date/ ← YYYY-MM-DD-.md (ADR-style) +│ ├── by-project/ ← mirror by project +│ └── decision-template.md +├── reviews/ ← weekly / monthly / quarterly / annual +├── archive/ ← notes / projects / imports +└── _agent/ + ├── context/ ← current-context.md and task bundles + ├── memory/ + │ ├── working/ ← transient, time-boxed + │ ├── episodic/ ← what happened, when + │ └── semantic/ ← durable facts/patterns (operator-preferences.md) + ├── sessions/ ← YYYY-MM-DD-HHMM-.md + ├── templates/ ← canonical note templates + ├── outputs/ ← briefs / drafts / summaries / synthesis + ├── skills/ ← active / archived + └── heartbeat/ +``` + +**Slug rules:** kebab-case, ASCII only, truncate to ~40 chars. + +--- + +## Canonical Frontmatter + +Every note starts with this block. Fill what applies; leave the rest empty rather than guessing. + +```yaml +--- +type: # see Note Types below +status: # active | draft | done | archived | complete +created: # YYYY-MM-DD (or YYYY-MM-DDTHH:mm for sessions) +updated: # YYYY-MM-DD +tags: [] +agent_written: false +source_notes: [] # plain relative paths as strings — NEVER [[wikilinks]] +--- +``` + +`agent_written: true` + a populated `source_notes` is the key signal separating +agent-managed content from human-authored content. When appending with POST, do +not rewrite frontmatter — the append goes after existing content. To change +`updated:` or `status:`, use PATCH with `Target-Type: frontmatter`. + +> **No `[[wikilinks]]` in frontmatter.** YAML parses `[[...]]` as nested lists, so wiki +> links there break and never render as clickable links in reading view. Put all +> cross-references in a **`## Related`** section in the note **body** (bulleted `[[links]]`). +> Frontmatter holds scalar/string metadata only; `source_notes` values are plain relative +> paths, not links. + +## Note Types + +`daily-note`, `weekly-note`, `monthly-note`, `project`, `project-update`, `area`, +`concept`, `reference`, `person`, `meeting`, `decision`, `review`, `session-log`, +`working-memory`, `episodic-memory`, `semantic-memory`, `context-bundle`, `skill`, +`draft`, `inbox-item`. + +--- + +## File-Specific Conventions + +### operator-preferences.md (`_agent/memory/semantic/`) + +The profile analog. Headings include `Operator`, `Fact / Pattern`, `Evidence`, +`Recommendation or Implication`, `Review Notes`. Append observed facts under the +right heading via PATCH. "The operator" is Bryan; do not attribute Jason's design +preferences to Bryan without evidence. + +### projects/active/\.md + +```markdown +--- +type: project +status: active +created: 2026-06-02 +updated: 2026-06-02 +tags: [] +agent_written: false +source_notes: [] +--- + +# Project Name + +## Current status +One paragraph, kept fresh via PATCH replace. + +## Decisions +- [[YYYY-MM-DD-decision-slug]] — one-line summary + +## Open threads +- [ ] unresolved thing + +## Log +- 2026-06-02: observation or update + +## Related +- [[areas/business/business-ops]] +``` + +### sessions/YYYY-MM-DD-HHMM-\.md + +See `session-log-template.md`. Note goldbrain uses an **HHMM time component** in the +filename (unlike a date-only convention). + +### decisions/by-date/YYYY-MM-DD-\.md + +ADR-style: Context → Decision → Consequences. Mirror a link into `by-project/`. + +### people/\.md + +`type: person`. Use lowercase kebab-case for the slug (e.g. `bryan-gilliom.md`). + +--- + +## Cross-References + +Use Obsidian wiki links freely: `[[note-name]]` or `[[folder/note]]`. The REST API +doesn't resolve them, but Obsidian does when the operator browses the vault. diff --git a/.source-references/references-only/obsidian (goldbrain) rest api key and address.txt b/.source-references/references-only/obsidian (goldbrain) rest api key and address.txt new file mode 100644 index 0000000..7b381b1 --- /dev/null +++ b/.source-references/references-only/obsidian (goldbrain) rest api key and address.txt @@ -0,0 +1,3 @@ +Bearer fb72065a05fabb28ae87c45880cc3b7aba4fd3f58e70297934145cef974e8ed8 + +https://goldbrainapi.mpm.to \ No newline at end of file diff --git a/.source-references/references-only/obsidian rest api documentation.txt b/.source-references/references-only/obsidian rest api documentation.txt new file mode 100644 index 0000000..1eb6cb5 --- /dev/null +++ b/.source-references/references-only/obsidian rest api documentation.txt @@ -0,0 +1 @@ +https://github.com/coddingtonbear/obsidian-local-rest-api \ No newline at end of file diff --git a/.source-references/references-only/reference vault/README.md b/.source-references/references-only/reference vault/README.md new file mode 100644 index 0000000..8d3ee4e --- /dev/null +++ b/.source-references/references-only/reference vault/README.md @@ -0,0 +1,25 @@ +# Agent Memory Index + +This is the entry point for Claude when reading memory. Files in `memory/` +are read on demand based on the conversation. + +## Read at session start + +1. `memory/profile.md` — facts about Jason, role, preferences +2. The most relevant file under `memory/projects/` if a specific project is in play + +## Write when + +- Jason says "remember", "save", or "log this" +- A non-obvious decision is made → `memory/decisions/` +- A working session ends with substance → `memory/sessions/` +- Unsure where it goes → `memory/inbox.md` + +## Folder map + +- `memory/profile.md` — persistent facts about Jason +- `memory/projects/.md` — long-running project state +- `memory/sessions/YYYY-MM-DD-.md` — per-conversation logs +- `memory/people/.md` — context about people +- `memory/decisions/-.md` — decision records +- `memory/inbox.md` — uncategorized notes to triage later diff --git a/.source-references/references-only/reference vault/memory/decisions/2026-05-19-cpas-backdated-snapshot-refresh.md b/.source-references/references-only/reference vault/memory/decisions/2026-05-19-cpas-backdated-snapshot-refresh.md new file mode 100644 index 0000000..27fcf9f --- /dev/null +++ b/.source-references/references-only/reference vault/memory/decisions/2026-05-19-cpas-backdated-snapshot-refresh.md @@ -0,0 +1,44 @@ +--- +type: decision +date: 2026-05-19 +project: cpas +tags: + - cpas + - snapshot + - backdating + - audit + - mpm +--- + +# [[CPAS]] — back-dated insert refreshes downstream snapshots + +## Context + +On `main` branch (post `ba2b631 documentation`, pre any roll-off model overhaul), the CPAS app stores `prior_active_points` as an immutable snapshot at violation insert time. The PDF endpoint reads this snapshot to render "Prior Active Points → New Total → Tier". + +When a violation is logged with a back-dated `incident_date` that precedes existing violations, the **new** violation's own snapshot is computed correctly, but **existing later-dated violations' snapshots are stale** — they were frozen before the back-dated event existed and so omit it from their 90-day prior window. Re-downloading their PDFs shows the pre-backdate prior/total/tier. + +## Decision + +Refresh downstream snapshots on back-dated insert. Treat back-dating as a *timeline rewrite* and exempt it from the otherwise strict snapshot-immutability rule. Negate, restore, amend, and hard delete are NOT timeline rewrites and continue to leave snapshots alone. + +## Implementation (in `server.js`) + +- New helper `recomputeSnapshotsAfter(employeeId, incidentDate)` finds all violations for the employee with `incident_date > new_date AND incident_date <= new_date + 90 days`, recomputes each via the existing `getPriorActivePoints()` formula, and only writes UPDATEs where the value changed. +- `POST /api/violations` now wraps the insert + recompute in a single `db.transaction()` so a partial failure can't leave the system with a new violation and stale sibling snapshots. +- When refresh affects ≥1 row, a `violation_snapshots_recomputed` audit entry is written with `reason: 'backdated_insert'`, `trigger_incident_date`, and an `affected[]` array of `{id, incident_date, old, new}` for full traceability. +- Forward-dated inserts (the common case) do zero UPDATEs — affected query returns rows but the equality check skips them. + +## Docs + +- `AGENTS.md` "Prior-Points Snapshot" section updated with the back-dating exception +- `AGENTS.md` "What NOT to Do" updated — the "do not modify prior_active_points" line now carves out the back-dating path explicitly + +## Verification + +- `node --check server.js` passes +- Not runtime-tested in this session (better-sqlite3 won't compile on local Node v24 — see project file). Verification path: docker build, log V1 with a recent date, log V2 with an earlier back-dated date, re-download V1's PDF, confirm "Prior Active Points" now includes V2. + +## Relationship to roll-off model overhaul + +The existing `projects/cpas.md` "Roll-off model fix (2026-05-27)" section describes a *different* implementation of `recomputeSnapshotsAfter` that widens the window to "all later violations" under a clean-cycle roll-off rule. That work is not on `main` as of today. If/when the roll-off overhaul lands on `main`, the helper's window scope will need to be widened to match (current scope is the legacy 90-day rolling window). diff --git a/.source-references/references-only/reference vault/memory/decisions/2026-05-27-cpas-rolloff-clean-cycle-model.md b/.source-references/references-only/reference vault/memory/decisions/2026-05-27-cpas-rolloff-clean-cycle-model.md new file mode 100644 index 0000000..8bf931b --- /dev/null +++ b/.source-references/references-only/reference vault/memory/decisions/2026-05-27-cpas-rolloff-clean-cycle-model.md @@ -0,0 +1,37 @@ +--- +type: decision +status: shipped +tags: + - cpas + - scoring + - roll-off + - mpm +updated: 2026-05-27 +--- + +# [[CPAS]] roll-off: clean-cycle model, JS as source of truth + +## Context + +System was implementing a literal per-violation rolling 90-day window. Jason reported that the handbook actually says "5 points roll off after 90 consecutive days of no violations" — i.e. any new violation should reset the countdown for everyone, not just for itself. + +## Decision + +Adopt the clean-cycle model: + +1. Roll-off amount per cycle: **5 points, oldest first** +2. Repeat cadence: **another full 90 clean days required** for each successive 5-point roll-off +3. Reset trigger: **any new non-negated violation** (negated violations don't reset) + +Implement all standing math in JS (`lib/rolloff.js` `computeStanding()`). Drop the `active_cpas_scores` SQL view — oldest-first partial allocation isn't cleanly SQL-expressible, and having both a SQL and JS implementation invites divergence. + +## Alternatives considered + +- Keeping the SQL view with the aggregate formula `total - 5*cycles_since_last_violation` and computing per-violation breakdown only in JS. Rejected: two implementations of the same rule = drift risk; dashboard scale at MPM is small enough that per-request JS computation is fine. +- "All points roll off at once after 90 clean days" or "oldest entire violation rolls off." Rejected by Jason in clarifying questions. + +## Consequences + +- `/api/employees/:id/expiration` response shape changed (was per-violation list, now `{ schedule: [...] }`). Frontend `ExpirationTimeline.jsx` updated to match — any third-party consumer of that endpoint would break. +- Existing `prior_active_points` snapshots on pre-fix violation rows are stale; existing "Backfill Snapshots" admin button recomputes them under the new model on demand. +- `recomputeSnapshotsAfter` no longer caps the affected window at +90 days — backdated inserts now scan all later violations, since under the new model an earlier total shift propagates indefinitely. diff --git a/.source-references/references-only/reference vault/memory/decisions/2026-05-28-file-obsidian-heading-resolver-bug.md b/.source-references/references-only/reference vault/memory/decisions/2026-05-28-file-obsidian-heading-resolver-bug.md new file mode 100644 index 0000000..1320a2d --- /dev/null +++ b/.source-references/references-only/reference vault/memory/decisions/2026-05-28-file-obsidian-heading-resolver-bug.md @@ -0,0 +1,152 @@ +--- +type: decision +date: 2026-05-28 +status: open +tags: [obsidian, rest-api, bug-report, upstream] +related: [[obsidian-memory-plugin]] +--- + +# 2026-05-28 — File upstream issue for Obsidian Local REST API heading resolver bug + +## Decision + +Draft and file a bug report at [coddingtonbear/obsidian-local-rest-api](https://github.com/coddingtonbear/obsidian-local-rest-api) for the heading-resolver failure that affects both `Target-Type: heading` PATCH and `GET /heading/...` reads. + +## Why + +- Bug persists across a major plugin version bump (3.6 → 4.1.1), so it's not a regression in a transient build — it's a real defect that's been sitting in the resolver for at least one release. +- The bug silently degrades the obsidian-memory skill: every documented PATCH-heading example in the skill's `references/api-reference.md` fails, forcing fallbacks to POST/PUT/frontmatter-PATCH. We have working workarounds, but they preclude surgical section edits that the skill instructs Claude to do. +- Reproducer is small (4 curl calls) and deterministic — high signal-to-noise for a maintainer. +- No alternative — only the upstream maintainer can fix it. Local workarounds will live in [[obsidian-memory-plugin]] indefinitely until this lands. + +## How to apply + +- The full draft (title, repro, variations tried, ruled-out causes, suspected cause) is at `D:\REMOTE CODING\unifi-access-dashboard\obsidian-rest-api-issue-draft.md` on the dashboard machine. +- Before filing: fill in two placeholders — Obsidian app version and vault filesystem. +- After filing: come back to this decision and update `status:` from `open` → `filed` with the issue URL; if/when fixed, mark `resolved` and remove the workaround section from [[obsidian-memory-plugin]]. + +## Context that won't be in the issue body + +- All testing was done against the vault at `https://10.2.0.2:27124` from Claude Code sessions over the LAN. +- The skill's documented PATCH-heading example (in `references/api-reference.md`) references a key that has a typo (`8c` instead of `e7` in one digit) — unrelated to this bug but worth noting if anyone tries to copy-paste from there. +- `Target-Type: block` also fails with `invalid-target`. Probably the same resolver but not verified — left out of the issue body to keep the report tight; can add as a follow-up comment if relevant. + +## Open + +- [ ] Fill in placeholders in the draft and post the issue +- [ ] Paste the issue URL back here under "How to apply" +- [ ] When fixed upstream: drop the workaround section from [[obsidian-memory-plugin]] and switch the skill back to PATCH-heading where it makes sense + +## Draft body (copy-paste ready) + +See `obsidian-rest-api-issue-draft.md` on the dashboard machine, or mirrored below: + +--- + +### Heading resolver broken: `Target-Type: heading` PATCH and `GET /heading/...` both fail on any valid heading (4.1.1) + +**Summary** + +In Obsidian Local REST API **4.1.1**, two endpoints that both rely on heading resolution always fail, even on a freshly written file with trivially-valid markdown headings: + +- `PATCH /vault/` with `Target-Type: heading` → HTTP 400 `invalid-target` +- `GET /vault//heading/` → HTTP 404 `Not Found` + +`Target-Type: frontmatter` PATCH on the same file works fine, so the PATCH route itself is healthy. The bug is isolated to the heading-resolution code path shared by these two endpoints. + +Also reproduced in **3.6** before upgrading; the 3.6 → 4.1.1 upgrade did not change the behavior. + +**Minimal reproducer** + +```bash +HOST="https://YOUR-HOST:27124" +KEY="YOUR_API_KEY" + +# 1. PUT a fresh, simple file (HTTP 204 expected) +cat > /tmp/repro.md <<'EOF' +--- +type: scratch +--- + +# Hello + +## Section A + +Content under A. + +## Section B + +Content under B. +EOF + +curl -sk -w "PUT: %{http_code}\n" -X PUT \ + -H "Authorization: Bearer $KEY" \ + -H "Content-Type: text/markdown" \ + --data-binary @/tmp/repro.md \ + "$HOST/vault/scratch/repro.md" + +# 2. PATCH append under heading "Section A" — expected 200, actual 400 invalid-target +echo "appended" > /tmp/p.md +curl -sk -w "\nPATCH heading: %{http_code}\n" -X PATCH \ + -H "Authorization: Bearer $KEY" \ + -H "Operation: append" \ + -H "Target-Type: heading" \ + -H "Target: Section A" \ + -H "Content-Type: text/markdown" \ + --data-binary @/tmp/p.md \ + "$HOST/vault/scratch/repro.md" + +# 3. GET the heading's content via URL path — expected 200, actual 404 +curl -sk -w "\nGET heading: %{http_code}\n" \ + -H "Authorization: Bearer $KEY" \ + "$HOST/vault/scratch/repro.md/heading/Section%20A" + +# 4. CONTROL: PATCH frontmatter — works (HTTP 200) +curl -sk -w "\nPATCH frontmatter: %{http_code}\n" -X PATCH \ + -H "Authorization: Bearer $KEY" \ + -H "Operation: replace" \ + -H "Target-Type: frontmatter" \ + -H "Target: type" \ + -H "Content-Type: application/json" \ + --data '"updated"' \ + "$HOST/vault/scratch/repro.md" +``` + +**Actual output** + +``` +PUT: 204 +{"message":"...invalid-target","errorCode":40080} PATCH heading: 400 +{"message":"Not Found","errorCode":40400} GET heading: 404 +PATCH frontmatter: 200 +``` + +**Variations tried (all fail identically with `invalid-target` / 404)** + +- Single-word heading (`Target: Section`) and multi-word (`Target: Section A`) +- URL-encoded header value (`Target: Section%20A`) +- `Operation: append`, `prepend`, and `replace` +- Both freshly-PUT files (LF endings) and files originally written by Obsidian +- `Target-Type: block` also returns `invalid-target` + +**What I ruled out** + +- CRLF / BOM in source file — fresh file was written by `curl --data-binary` with LF-only content +- Spaces in heading text — single-word headings fail the same way +- URL encoding of `Target:` header value — raw and percent-encoded both fail +- PATCH route generally broken — `Target-Type: frontmatter` succeeds on the same file +- Version regression in 4.1.1 — same behavior in 3.6 before upgrading + +**Environment** + +- Obsidian Local REST API: 4.1.1 (also reproduced in 3.6) +- Obsidian: `` +- OS hosting Obsidian: `` +- Client: curl over HTTPS to :27124 with `-k` (self-signed cert) +- Vault filesystem: `` + +**Suspected cause** + +Since `GET /vault//heading/` and `Target-Type: heading` PATCH fail in lockstep (and frontmatter resolution works fine on the same request path), the most likely location is whichever helper enumerates headings within a parsed file's AST — perhaps it's getting an empty list, or matching on the wrong field. + +Happy to bisect or add logging if you can point me at the relevant file. diff --git a/.source-references/references-only/reference vault/memory/inbox.md b/.source-references/references-only/reference vault/memory/inbox.md new file mode 100644 index 0000000..fc93fb8 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/inbox.md @@ -0,0 +1,13 @@ +--- +type: inbox +updated: 2026-05-27 +--- + +# Inbox + +Untriaged memory entries. One line per item, prefixed with date. +Promote to the right file when convenient. + +- 2026-05-27 — `better-sqlite3` native build fails on local Node v24 (gyp errors); builds fine in `node:20-alpine`. For projects using it (cpas at minimum), verify via container build rather than local `node` invocation. + +- 2026-05-19 — CPAS: shipped back-dated-insert snapshot refresh on `main` (helper `recomputeSnapshotsAfter` in server.js, transactional, audit-logged as `violation_snapshots_recomputed`). Decision record: [[2026-05-19-cpas-backdated-snapshot-refresh]]. Note: this lives on `main` which is still the legacy 90-day-rolling model — different universe from the roll-off overhaul described in [[cpas]]. Window scope will need widening when roll-off lands on `main`. diff --git a/.source-references/references-only/reference vault/memory/people/bryan-gilliom.md b/.source-references/references-only/reference vault/memory/people/bryan-gilliom.md new file mode 100644 index 0000000..386cd9e --- /dev/null +++ b/.source-references/references-only/reference vault/memory/people/bryan-gilliom.md @@ -0,0 +1,17 @@ +--- +type: people +status: active +tags: + - mpm + - boss + - ceo +updated: 2026-05-30 +--- + +# Bryan Gilliom + +CEO of Message Point Media (MPM). Jason's boss. + +## Notes +- Authored the "Moving Forward" / Working Framework document governing Mitch Tankersley's diminished-autonomy period (see [[mitch-tankersley]]). +- Jason is waiting on Bryan to provide two values to fill into Mitch's Working Framework: the Amazon no-approval spend threshold, and the framework's effective date. diff --git a/.source-references/references-only/reference vault/memory/people/mitch-tankersley.md b/.source-references/references-only/reference vault/memory/people/mitch-tankersley.md new file mode 100644 index 0000000..68ada23 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/people/mitch-tankersley.md @@ -0,0 +1,130 @@ +--- +type: people +status: active +tags: + - employee + - performance + - diminished-autonomy + - daily-tracker + - mitch + - mpm +updated: 2026-05-30 +--- + +# Mitch Tankersley — Daily Progress Tracker + +## About + +Mitch Tankersley is an employee at MPM (Message Point Media) currently operating under **diminished autonomy** — a structured accountability period requiring daily check-in and check-out reporting to Jason. + +**Manager:** Jason (jason@messagepoint.tv) +**Status:** Diminished autonomy — daily task accountability required +**Tracker started:** 2026-05-28 + +**Reporting method:** Mitch reports his check-ins and check-outs directly to Jason via **Google Chat**. Jason logs all entries here as his direct supervisor — Mitch does not write to this file himself. + +--- + +## Working Framework + +Condensed from the supervisor's "Moving Forward" document (MPM internal, confidential). Defines the terms of the diminished-autonomy period. + +### Schedule +- In-office Monday–Friday, **9:00 AM – 6:00 PM**. No remote work under any circumstance. +- Any absence during business hours requires advance supervisor approval and is recorded as PTO. +- Exception: authorized out-of-town deployments coordinated through Finance. + +### Daily Check-In (Start & End of Day) +- **Start of day:** Message supervisor with priorities before starting work. +- **End of day:** Wrap message with accomplishments — include links, artifacts, or photos where possible. "If you built it, show it." +- Suggested templates: + - **SOD** — "Morning. Today: [1] [task] · [2] [task] · [3] [task]. Blockers: [none / note]" + - **EOD** — "Done for the day. Completed: [item — link or pic]. In progress: [item, where I left off]. Tomorrow: [carry-forward]. Artifacts: [attach or link anything produced]" + +### Company Vehicle (interim — pending purchase completion) +- Business use only; no personal use. +- Pay for fuel out of pocket; submit business miles for reimbursement at the standard IRS mileage rate. +- Keep a mileage log — date, destination, business purpose, miles. +- Once vehicle purchase is finalized, terms convert to the loan agreement. + +### Spending & Expenses +- Restricted Spend card with Finance-managed limits. +- Approval required before purchasing — text Tiffany or Jason for fast turnaround. +- Amazon under $[limit TBD]: no approval needed; use company shared payment method. +- **Itemized receipts — no exceptions.** Every purchase requires an itemized receipt showing exactly what was bought; a total-only receipt is not sufficient. Missing or non-itemized receipts result in the pre-paid card not being replenished, or the amount deducted directly from his paycheck to replenish it. + +### Travel Coordination +- All airfare, lodging, and vehicle rentals booked directly by MPM Finance. +- Submit travel needs to Finance at least **48 hours in advance**. +- All travel spend via Ramp pre-paid card — itemized receipts required (see Spending). +- Standard in-office schedule resumes immediately upon return to Birmingham. + +### Systems & Credentials +- All accounts, software licenses, subscriptions, and credentials are MPM property at all times. +- Work with Jason to move all company-related accounts and services to a company payment method. +- Document all logins and passwords in Shared Apple Passwords. +- Access is subject to review, reassignment, or revocation at management's discretion without advance notice. + +### Knowledge Transfer & Documentation +- Active documentation of all systems, processes, and integrations he owns or manages. +- Use Plaud to record walkthroughs and process notes — reduces overhead of writing from scratch. +- Coordinate with Jason on documentation priorities, format, and handoff. +- Junior shadow oversight of work product is in effect. + +### Path Forward +- Every **90 days of clean performance** is an automatic step toward restored autonomy (flexibility, trust, discretion over time and tools). [[cpas]] + +--- + +## Instructions for Daily Entries + +Each workday requires two entries: a **Morning Check-In** and an **End-of-Shift Check-Out**. + +### Morning Check-In (start of shift) +Mitch submits the tasks he **plans** to work on that day before beginning work. + +Format: +``` +### YYYY-MM-DD — Check-In +**Time:** HH:MM AM/PM +**Planned Tasks:** +- [ ] Task description +- [ ] Task description +- [ ] Task description +``` + +### End-of-Shift Check-Out (end of shift) +Mitch submits the tasks he **actually made progress on** before leaving. + +Format: +``` +### YYYY-MM-DD — Check-Out +**Time:** HH:MM AM/PM +**Progress Made:** +- [x] Task completed / description of progress +- [-] Task partially completed — notes on where it stands +- [ ] Task not started — brief reason if applicable +**Notes:** (optional — blockers, context, carryover) +``` + +--- + +## Daily Log + +### 2026-05-28 — Check-Out +**Time:** End of shift +**Progress Made:** +- [x] Mobile screen mounting patterns — completed +- [-] Tucson 3D prints — in progress, status unknown +**Notes:** Reported via Google Chat to Jason. + +### 2026-05-29 — Check-In +**Status:** Never submitted. No morning check-in received. + +### 2026-05-29 — Check-Out +**Time:** End of shift +**Progress Made:** +- [-] Tucson 3D prints — still in progress. Mitch reports it is "a very difficult print, consuming my time, prompting redesign. Trying to improve final result." No other updates given. +**Notes:** No morning check-in was submitted for this date. + +**Manager assessment (Jason):** This appears to be an inefficient use of time. Tucson is a one-off project with no real gain versus simply outsourcing the work. Continued in-house iteration/redesign is not justified by the payoff. diff --git a/.source-references/references-only/reference vault/memory/profile.md b/.source-references/references-only/reference vault/memory/profile.md new file mode 100644 index 0000000..dde990a --- /dev/null +++ b/.source-references/references-only/reference vault/memory/profile.md @@ -0,0 +1,85 @@ +--- +type: profile +updated: 2026-05-28 +--- + +# Profile + +> Persistent facts about Jason. Append observations as they emerge; +> promote stable ones to a top-level section. + +## Role + +Jason works at **Message Point Media (MPM)** — a digital signage company (~2,000-display installed base). He is a developer and builder who runs Claude CoWork skills and plugins for the MPM team. He also runs his own wireless ISP, **ALWISP** (Alabama mesh networking), and builds a wide range of personal and commercial self-hosted applications. + +## Communication preferences + +## Tools and stack + +### Preferred languages and runtimes +- **Primary:** Node.js + TypeScript for application work +- **Secondary:** Python for tooling, automation, and AI integrations (FastAPI) +- **Frontend:** React 18 + TypeScript + Vite; Tailwind CSS; Svelte (used in pnger) +- **ORM/DB:** Prisma + SQLite as default; PostgreSQL for production-grade apps +- **Build/deploy:** Single Docker container pattern — nearly every app ships as one container + +### Infrastructure +- Runs an **Unraid** server as his primary self-hosting platform +- Personal Gitea at **git.alwisp.com** — personal repos under `jason/` user +- Work Gitea at **git.mpm.to** — MPM org repos (plugin: `git-mpm`) +- **TotalMCP** unified MCP gateway runs at `10.2.0.35:8811` on Unraid `br0` +- Obsidian vault accessible at `10.2.0.2:27124` (self-signed cert, `-k` always needed) +- Gitea CI runners used for building Docker images (e.g., stepview) + +### CoWork plugins and skills +Jason maintains a suite of Claude CoWork plugins at git.mpm.to and git.alwisp.com. Key ones: +- `mpm-brand-voice-plugin` — MPM brand voice enforcement +- `odoo-mpm-plugin` / `odoo-plugin-creation` — Odoo ERP access +- `display-catalog-plugin` — MP.TV product catalog generation +- `prompt-optimizer` — transforms rough requests into polished prompts +- `git-personal` — personal Gitea (git.alwisp.com) +- `git-mpm` — work Gitea (git.mpm.to) + +## Personal projects (git.alwisp.com/jason) + +| Repo | What it is | +| ---------------------- | ------------------------------------------------------------------------- | +| **[[alwisp]]** | Dockerized LAMP website for his wireless ISP | +| **[[breedr]]** | Dog breeding genealogy management system | +| **[[codedump]]** | Internal dashboard for tracking AI tools and coding projects | +| **[[codexium-odoo]]** | CODEXIUM MRP platform — Odoo variant | +| **[[cpas]]** | CPAS violation tracker with Puppeteer PDF generation | +| **[[email]]** | Google Workspace email signature manager | +| **[[fabdash]]** | Fabrication project management and scheduling dashboard | +| **[[family-planner]]** | Self-hosted family dashboard (calendars, chores, meals, screensaver) | +| **[[inven]]** | Inventory management with BOMs, orders, invoicing on SQLite | +| **[[memer]]** | Self-hosted meme gallery with Telegram/SMS quick-share | +| **[[mempalace]]** | Server-mode MemPalace fork — shared AI memory palace over LAN | +| **[[mrp]]** | CODEXIUM MRP — manufacturing resource planning platform | +| **[[mrp-qrcode]]** | MRP with QR traveler cards, operator scan flow, in-browser STEP viewer | +| **[[nyaa-crawler]]** | Nyaa.si anime torrent tracker and auto-downloader | +| **[[pos]]** | Full-stack TypeScript point-of-sale (Android + Node + React) | +| **[[rack-planner]]** | RackMapper — network rack visualizer and service dependency mapper | +| **[[stepview]]** | Self-hosted in-browser 3D STEP file viewer (OpenCascade WASM + three.js) | +| **[[storybid]]** | Charity auction platform with PWA offline bidding and Stripe payments | +| **[[totalmcp]]** | Unified MCP gateway for the ALPHA stack (Claude Code, Codex, Antigravity) | +| **[[ui-tracker]]** | Unifi Store stock monitor with Telegram alerts | +| **[[pnger]]** | PNG editor/resizer — TypeScript + Svelte + Sharp | +| **[[qrknit]]** | Commercial QR code generator and URL shortener (own org: qrknit/qrknit) | + +## Notes + +- Gitea file uploads must use Python + temp files for base64 encoding — `echo -n | base64` causes corruption +- Nearly all apps follow the single-container Docker pattern designed for Unraid deployment +- Jason builds for himself and for MPM — personal projects skew toward home automation, media, and fabrication tooling + +### Deployment workflow +- **CI/CD:** Push to Gitea (`git.alwisp.com`) → Gitea Actions → Docker build → push to `registry.alwisp.com` +- **Gitea Actions runner image:** `catthehacker/ubuntu:act-latest` +- **Image tag pattern:** `registry.alwisp.com/{owner}/{repo}:latest` +- **Deployment target:** Unraid Docker GUI (manual container creation after image push) +- **Network preference:** Always **Custom: br0** — dedicated LAN IP per container, subnet `10.2.0.0/24`; never bridge; reason: direct app-to-app communication without port mapping +- **Volume root:** `/mnt/user/appdata/{app-name}/` on Unraid host +- **Privileged containers:** OFF by default +- **Tailscale on containers:** OFF by default +- Full deployment reference: [[unraid-deployment]] diff --git a/.source-references/references-only/reference vault/memory/projects/agents.md b/.source-references/references-only/reference vault/memory/projects/agents.md new file mode 100644 index 0000000..a3fc845 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/agents.md @@ -0,0 +1,77 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/agents +repo_url: https://git.alwisp.com/jason/agents +language: Markdown +branch: main +tags: [repo, jason] +updated: 2026-05-29 +--- + +# agents + +**Repository:** [jason/agents](https://git.alwisp.com/jason/agents) · branch `main` · Markdown + +## Summary + +Portable drop-in markdown instruction suite for AI coding agents — provides AGENTS.md, skill index, routing hubs, and specialized skill files to copy into any repo + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# Drop-In Agent Instruction Suite + +This repository is a portable markdown instruction pack for coding agents. + +Copy these files into another repository to give the agent: +- a root `AGENTS.md` entrypoint, +- a central skill index, +- category hubs for routing, +- specialized skill files for common software, docs, UX, marketing, and ideation tasks. + +## Structure + +- `AGENTS.md` - base instructions and routing rules +- `DEPLOYMENT-PROFILE.md` - agent-readable prefilled deployment defaults +- `INSTALL.md` - copy and customization guide for other repositories +- `PROJECT-PROFILE-WORKBOOK.md` - one-time questionnaire for staging defaults +- `SKILLS.md` - canonical skill index +- `ROUTING-EXAMPLES.md` - representative prompt-to-skill routing examples +- `hubs/` - category-level routing guides +- `skills/` - specialized reusable skill files + +## Design Goals + +- Plain markdown only +- Cross-agent portability +- Implementation-first defaults +- On-demand skill loading instead of loading everything every session +- Context-efficient routing for large skill libraries +- Prefilled deployment defaults without per-install questioning +- Repo-local instructions take precedence over this bundle + +## Intended Workflow + +1. The agent reads `AGENTS.md`. +2. The agent reads `DEPLOYMENT-PROFILE.md` when it is filled in. +3. The agent checks `SKILLS.md`. +4. The agent opens only the relevant hub and skill files for the task. +5. The agent combines multiple skills when the task spans several domains. + +## Core Categories + +- Software development +- Debugging +- Documentation +- UI/UX +- Marketing +- Brainstorming + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/alwisp.md b/.source-references/references-only/reference vault/memory/projects/alwisp.md new file mode 100644 index 0000000..8142a62 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/alwisp.md @@ -0,0 +1,77 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/alwisp +repo_url: https://git.alwisp.com/jason/alwisp +language: Hack +branch: main +tags: [repo, jason] +updated: 2026-05-29 +--- + +# alwisp + +**Repository:** [jason/alwisp](https://git.alwisp.com/jason/alwisp) · branch `main` · Hack + +## Summary + +Dockerized LAMP stack website for ALWISP, Alabama's wireless ISP and mesh networking company + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# ALWISP – Mesh Network Solutions + +> Dockerized LAMP stack website for Alabama's wireless ISP and mesh networking company. + +--- + +## Table of Contents + +- [Stack Overview](#stack-overview) +- [Installation – Unraid](#installation--unraid) +- [Environment Variables](#environment-variables) +- [Project Structure](#project-structure) +- [Roadmap & Milestones](#roadmap--milestones) +- [Updating the Site](#updating-the-site) +- [Useful Commands](#useful-commands) + +--- + +## Stack Overview + +| Container | Image | Purpose | +|---|---|---| +| `alwisp_web` | PHP 8.2 + Apache | Serves the website | +| `alwisp_db` | MySQL 8.0 | Database (internal only) | +| `alwisp_pma` | phpMyAdmin (optional) | DB admin UI on port 8080 | + +Each container is deployed individually through the Unraid Container Builder and connected via the `br0` bridge network, giving both the web container and the database container their own dedicated LAN IP addresses. The web container reaches the database by its fixed LAN IP. Data persists in a named Docker volume (`db_data`) and survives container restarts and rebuilds. + +--- + +## Installation – Unraid + +### Prerequisites + +- Unraid 6.10 or later +- **Community Applications** plugin installed +- **Docker** enabled (Settings → Docker → Enable Docker: Yes) +- **User Scripts** plugin (recommended, for scheduled tasks) +- `br0` enabled — your Unraid host NIC must be bridged (Settings → Network → Enable Bridging: Yes) +- Decide on **two free LAN IPs** before you start — one for the web container, one for the database. Example: `192.168.1.100` (web) and `192.168.1.101` (db). Reserve these in your router's DHCP settings so they are never auto-assigned. + +--- + +### Step 1 – Clone the repository onto your Unraid cache drive + + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/breedr.md b/.source-references/references-only/reference vault/memory/projects/breedr.md new file mode 100644 index 0000000..5ca7611 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/breedr.md @@ -0,0 +1,75 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/breedr +repo_url: https://git.alwisp.com/jason/breedr +language: JavaScript +branch: main +tags: [repo, jason] +updated: 2026-05-29 +--- + +# breedr + +**Repository:** [jason/breedr](https://git.alwisp.com/jason/breedr) · branch `main` · JavaScript + +## Summary + +Reactive dog breeding genealogy management system — pedigree mapping, litter records, and ancestor/descendant views in a single Docker container + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# BREEDR - Dog Breeding Genealogy Management System + +A reactive, interactive dog breeding genealogy mapping system for professional kennel management. + +--- + +## 🌟 Recent Highlights (v0.8.0) +- **✅ Reverse Pedigree** — Toggle between ancestors and descendants view for full lineage tracking. +- **✅ External Dog Mapping** — Assign parents to external dogs, allowing for full genealogy of outside lines. +- **✅ Universal Parent Selection** — Select any dog (kennel or external) as a sire/dam from any profile. + +--- + +## 🚀 Quick Start + +### 1. Docker Deployment (Recommended) +```bash +git clone https://git.alwisp.com/jason/breedr.git +cd breedr +docker-compose up -d --build +``` +Access at: `http://localhost:3000` + +### 2. Manual Development Setup +```bash +npm install +npm run dev +``` +> **Note:** The database initializes automatically on first boot. No manual migrations are required. + +--- + +## 🐕 Managing Your Kennel + +- **Adding Dogs**: Go to the **Dogs** page, click **Add New Dog**. You can mark dogs as **External** if they aren't in your kennel but are needed for pedigree mapping. +- **Champion Tracking**: Toggle the **Champion** status to title dogs. Offspring will automatically display the "Champion Bloodline" badge. +- **Photo Management**: Multiple high-quality photos per dog with a compact gallery view. +- **Litter Tracking**: Link puppies to breeding records automatically to track weight and health from birth. + +## 🧬 Breeding & Genetics + +- **Interactive Pedigree**: 5-generation trees with zoom/pan. Toggle the **Reverse Pedigree** switch to see descendant lineage. +- **Trial Pairing Simulator**: Calculate Wright's Inbreeding Coefficient (COI) instantly. Identifies common ancestors and providing risk badges (Low/Moderate/High). + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/codedump.md b/.source-references/references-only/reference vault/memory/projects/codedump.md new file mode 100644 index 0000000..a2308ab --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/codedump.md @@ -0,0 +1,84 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/codedump +repo_url: https://git.alwisp.com/jason/codedump +language: TypeScript +branch: main +tags: [repo, jason] +updated: 2026-05-29 +--- + +# codedump + +**Repository:** [jason/codedump](https://git.alwisp.com/jason/codedump) · branch `main` · TypeScript + +## Summary + +Internal dashboard for tracking AI tools and coding projects — shows completion status, links documentation, and manages team access via admin accounts and PINs + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +_Source: PROJECT.md_ + +# CODEDUMP + +Internal dashboard for tracking AI tools and coding projects. Provides a high-level overview of what the team is building, what tools are available, and the completion status of active work — all in one place. + +--- + +## Purpose + +CODEDUMP gives teams a single place to: + +- Track AI tools and coding projects with completion percentages +- Attach markdown documentation and project files +- Link to internal/external URLs and Google Drive sources +- Highlight new tools available to the team +- Manage access via admin accounts and 4-digit user PINs + +--- + +## Tech Stack + +| Layer | Technology | +|---|---| +| Frontend | React 18 + TypeScript + Vite | +| Styling | Tailwind CSS (dark mode, CSS variable theming) | +| Backend | Node.js + Express + TypeScript | +| Database | SQLite via `better-sqlite3` | +| Auth | JWT (12h expiry) + bcryptjs (admin passwords) + HMAC-SHA256 (user PINs) | +| File uploads | Multer (local disk storage) | +| Markdown | `react-markdown` + `remark-gfm` | +| Container | Docker (multi-stage build, single container) | + +--- + +## Project Structure + +``` +codedump/ +├── client/ # React frontend +│ ├── src/ +│ │ ├── api/index.ts # Typed fetch wrappers (JWT injected automatically) +│ │ ├── hooks/ +│ │ │ ├── useAuth.ts # AuthContext — JWT storage, login/logout +│ │ │ └── useSettings.ts # SettingsContext — branding, accent color +│ │ ├── components/ +│ │ │ ├── layout/ +│ │ │ │ ├── Layout.tsx # App shell (sidebar + outlet) +│ │ │ │ └── Sidebar.tsx # Nav — auth-aware, admin section, logout +│ │ │ ├── projects/ +│ │ │ │ ├── ProjectCard.tsx # Card with progress bar, links, tags +│ │ │ │ └── ProjectForm.tsx # Create/edit form with color picker + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/codexium-odoo.md b/.source-references/references-only/reference vault/memory/projects/codexium-odoo.md new file mode 100644 index 0000000..680173e --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/codexium-odoo.md @@ -0,0 +1,56 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/codexium-odoo +repo_url: https://git.alwisp.com/jason/codexium-odoo +language: TypeScript +branch: main +tags: [repo, jason] +updated: 2026-05-29 +--- + +# codexium-odoo + +**Repository:** [jason/codexium-odoo](https://git.alwisp.com/jason/codexium-odoo) · branch `main` · TypeScript + +## Summary + +CODEXIUM MRP platform (Odoo variant) — modular Manufacturing Resource Planning with React, Express, Prisma, SQLite, full CRM, inventory, and BOM management + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# CODEXIUM + +Foundation release for a modular Manufacturing Resource Planning platform built with React, Express, Prisma, SQLite, and a single-container Docker deployment. + +## Documentation Maintenance + +- Keep [CHANGELOG.md](D:/CODING/mrp-codex/CHANGELOG.md) updated for shipped features, workflow changes, and notable operational updates. +- Keep [README.md](D:/CODING/mrp-codex/README.md), [INSTRUCTIONS.md](D:/CODING/mrp-codex/INSTRUCTIONS.md), [STRUCTURE.md](D:/CODING/mrp-codex/STRUCTURE.md), [ROADMAP.md](D:/CODING/mrp-codex/ROADMAP.md), [SHIPPED.md](D:/CODING/mrp-codex/SHIPPED.md), and [UNRAID.md](D:/CODING/mrp-codex/UNRAID.md) aligned when changes affect their scope. + +Current foundation scope includes: + +- authentication and RBAC +- company branding and theme settings, including startup brand-theme hydration across refresh +- CRM customers and vendors with create/edit/detail workflows +- CRM search, filtering, status tagging, and reseller hierarchy +- CRM contact history, account contacts, and shared attachments +- inventory item master, BOM, warehouse, stock-location, and stock-transaction flows +- inventory transfers, reservations, and available-stock visibility +- inventory SKU master builder with family-scoped sequence generation and branch-aware taxonomy management +- staged thumbnail image attachment on inventory item create/edit workflows, with detail-page thumbnail display +- sales quotes and sales orders with searchable customer and SKU entry +- sales approvals, approval stamps, automatic revision history, and revision comparison on quotes and sales orders +- purchase orders with searchable vendor and SKU entry, restricted to purchasable inventory items +- purchase-order revision history and revision comparison across commercial and receipt changes + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/cpas.md b/.source-references/references-only/reference vault/memory/projects/cpas.md new file mode 100644 index 0000000..beb4ead --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/cpas.md @@ -0,0 +1,96 @@ +--- +type: project +status: active +tags: + - cpas + - mpm-internal + - sqlite + - express + - react + - puppeteer + - mpm +updated: 2026-05-27 +--- + +# CPAS Violation Tracker + +Internal MPM tool for tracking employee CPAS (Corrective Performance Action System) violations. Single Docker container, self-contained. Repo: `git.alwisp.com/jason/cpas` (also pushed to git.mpm.to as MPM internal). + +Local path: `F:\CODING\cpas\cpas`. + +## Stack + +- **Backend:** Node.js + Express + `better-sqlite3` (better-sqlite3 won't compile on local Node v24 — builds fine in `node:20-alpine` Docker) +- **Frontend:** React 18 + Vite, axios for API calls, dark theme inline styles (no Tailwind here) +- **PDF:** Puppeteer-core driving Chromium in the container +- **DB:** SQLite at `/data/cpas.db`, WAL mode, foreign keys ON. Schema lives in `db/schema.sql` with programmatic migrations in `db/database.js` +- **Port:** 3001 +- **Deployment:** Single container on Unraid, volume `/data` for the DB + +## Key architecture notes + +- Violations carry a 90-day rolling window. Each violation stores a `prior_active_points` **snapshot** at submission so its PDF always shows the score *as it was on the incident date*. Snapshots auto-refresh on back-dated inserts and via a manual "Backfill Snapshots" button per employee. +- Negate = soft delete (reversible). Hard delete is also supported. Both are audit-logged. +- Append-only `audit_log` table records every write action. +- Custom violation types stored in `violation_types` table; type_key prefixed with `custom_` to avoid collisions. + +## Authentication (added 2026-05-27) + +- **Login screen** gates the entire app. Every `/api/*` route except `/api/health` and `/api/auth/login` requires a `Bearer` token. +- **Bootstrap admin** created/synced from `ADMIN_USERNAME` / `ADMIN_PASSWORD` env vars on every container start — its password is owned by Docker (cannot be changed in UI; UI changes overwritten on restart). Default `ADMIN_PASSWORD=changeme` must be overridden at deploy. +- **Password hashing:** Node built-in `crypto.scryptSync` (no new deps). Stored as `scrypt$$`. +- **Sessions:** DB-backed in `sessions` table, 7-day TTL, token = `crypto.randomBytes(32).toString('hex')`. Sessions survive container restarts. +- **Roles:** `admin` and `user`. Admin sees a **Users** button in the nav to add/delete users and reset passwords. +- **Frontend:** axios request interceptor injects `Authorization: Bearer ` from localStorage on every call; response interceptor clears token + falls back to login on 401. Covers all components including blob PDF downloads (which use axios with `responseType: 'blob'`, no direct anchor links). + +## Files of note + +- `auth.js` — auth module (hashing, sessions, user CRUD, middleware, `bootstrapAdmin()`) +- `server.js` — `app.use('/api', auth.requireAuth)` placed after `/api/health` and `/api/auth/login` so those stay public; all routes below are protected +- `db/database.js` — `users` and `sessions` tables added +- `client/src/auth.js` — axios interceptors + token helpers +- `client/src/components/LoginModal.jsx` — login popup +- `client/src/components/UserManagementModal.jsx` — admin Users panel +- `client/src/App.jsx` — auth gate (`authChecked`/`user` state), logout button, conditional Users button +- `Dockerfile` — `ENV ADMIN_USERNAME=admin` and `ENV ADMIN_PASSWORD=changeme` defaults +- `client/src/components/ReadmeModal.jsx` — in-app admin guide; updated with "Authentication & User Accounts" section +- `README_UNRAID_INSTALL.md` — adds steps 5.5 Variables 3+4 (admin env vars), login note in Verify, troubleshooting rows for forgotten admin password + +## Current status + +Authentication shipped (2026-05-27). Backend syntax-checks pass; client builds clean. Could not verify locally because better-sqlite3 fails to compile on Node v24 — verification requires building/running the Docker container. + +## Open considerations + +- No expanded role model yet (only admin/user). Future: supervisor-scoped or read-only roles. +- No password-change UI for non-admin users (they ask an admin to reset). Could add. +- Sessions table has no periodic cleanup of expired tokens; expired tokens are pruned lazily on use. + +## Roll-off model fix (2026-05-27) + +Earlier "90-day rolling window per violation" wording above is **superseded**. The handbook actually specifies a *clean-cycle* roll-off: points only retire after 90 consecutive days with NO new violation, and any new non-negated violation resets the clock for the whole employee. Each completed clean cycle removes 5 points oldest-first; each successive 5-point roll-off needs another fresh 90 clean days. + +The old per-violation expiry was rolling whole violations off independently 90 days from their own incident date — so a new violation didn't reset the countdown on earlier ones. Bug surfaced by Jason; fixed same session. + +### Implementation + +- `lib/rolloff.js` (new) — pure `computeStanding(violations, asOf)` is the **single source of truth**. Returns `{ activePoints, totalPoints, rolledOffPoints, cycles, violationCount, lastViolationDate, nextRolloffDate, perViolation, schedule }`. Verified with scenario tests (single violation, two-violation reset case, multi-cycle decay). +- `active_cpas_scores` SQL view **retired** (dropped in `db/database.js`, removed from `schema.sql`). SQL can't cleanly express oldest-first partial allocation, so all standing computation moved to JS to avoid SQL/JS divergence. +- `server.js` rewired: `/score`, `/dashboard`, `/expiration`, `getPriorActivePoints`, PDF endpoint, and `recomputeSnapshotsAfter` all go through the helper. Dashboard now fetches all non-negated violations once, buckets per employee, and computes in JS (fine at MPM scale). +- `/expiration` response shape changed from a list of per-violation rows to `{ active_points, last_violation_date, next_rolloff_date, schedule: [{date, points_off, points_after, days_remaining}] }`. +- `recomputeSnapshotsAfter` window widened: under the new model an earlier backdated insert shifts every later violation's snapshot (not just within 90 days), so it now scans all later violations. +- Frontend: `ExpirationTimeline.jsx` re-rendered as a roll-off schedule with a "clock resets on any new violation" note. `ViolationForm.jsx` label changed from "violations in last 90 days" → "active violations". + +### Migration / backfill posture + +- **Automatic on restart:** every live read (dashboard, score, expiration, PDF current standing, prior points for NEW inserts). +- **Needs manual backfill:** `prior_active_points` already stored on pre-fix violation rows — they were frozen under the old rule. Existing "Backfill Snapshots" button (`POST /api/employees/:id/recompute-snapshots`) rewrites them per employee. Skip unless historical PDFs matter. + +### Files touched + +- `lib/rolloff.js` (new) +- `db/database.js` (drop view) +- `db/schema.sql` (drop view) +- `server.js` (helper require, `loadViolations`/`standingFor`, all 5 endpoint rewires) +- `client/src/components/ExpirationTimeline.jsx` (full rewrite of render) +- `client/src/components/ViolationForm.jsx` (label tweak) diff --git a/.source-references/references-only/reference vault/memory/projects/email.md b/.source-references/references-only/reference vault/memory/projects/email.md new file mode 100644 index 0000000..f410b49 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/email.md @@ -0,0 +1,74 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/email +repo_url: https://git.alwisp.com/jason/email +language: HTML +branch: main +tags: [repo, jason] +updated: 2026-05-29 +--- + +# email + +**Repository:** [jason/email](https://git.alwisp.com/jason/email) · branch `main` · HTML + +## Summary + +Self-hosted Dockerized Google Workspace email signature manager — syncs users from Google Directory and pushes HTML signatures directly to Gmail via API + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# Email Signature Manager + +A self-hosted, Dockerized Google Workspace email signature manager. +Runs as a single container — designed for Unraid but works on any Docker host. +See [INSTALL.md](INSTALL.md) for Unraid-specific instructions. + +## Features + +- **Automated Directory Sync** — Pulls user data from Google Workspace Directory API +- **HTML Signature Renderer** — Per-user signatures via Handlebars templates +- **Gmail API Integration** — Pushes signatures directly to Gmail (web + mobile) +- **Nightly Sync** — Automated batch push via configurable cron schedule +- **Web Admin UI** — Management dashboard with live template editor +- **Template Versioning** — Save multiple versions and recall them later +- **Test Mode** — Single-user push for safe testing and onboarding +- **Audit Logging** — SQLite-backed history of every push event +- **Secure Access** — Basic auth protected management interface +- **Self-Hosted** — Single container with internal SQLite, no external DB needed + +--- + +## Logo & Image Hosting + +All images referenced in the signature template must be publicly accessible via HTTPS. +The default logo URL is: +``` +https://alwisp.com/uploads/logo.png +``` +Upload your logo and any other signature images to `https://alwisp.com/uploads/` and +reference them by full URL in the template. The logo URL can also be changed live +in the Template Editor UI without rebuilding the container. + +--- + +## Environment Variables + +All secrets and configuration are passed as **environment variables at runtime**. +No `.env` file is committed to this repo — see `.env.example` for all variable names. + +| Variable | Description | Default | +|---|---|---| +| `GOOGLE_ADMIN_EMAIL` | Workspace admin email (e.g. jason@messagepoint.tv) | *(required)* | + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/fabdash.md b/.source-references/references-only/reference vault/memory/projects/fabdash.md new file mode 100644 index 0000000..364d1ac --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/fabdash.md @@ -0,0 +1,79 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/fabdash +repo_url: https://git.alwisp.com/jason/fabdash +language: JavaScript +branch: main +tags: [repo, jason] +updated: 2026-05-29 +--- + +# fabdash + +**Repository:** [jason/fabdash](https://git.alwisp.com/jason/fabdash) · branch `main` · JavaScript + +## Summary + +FABDASH: fabrication project management and scheduling dashboard — dark/gold-themed React + Flask + SQLite single-container app for fabrication workflow management + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# FABDASH + +**Fabrication Dashboard** — A sleek, modern project management & scheduling application built for fabrication workflows. +Repo: https://github.com/jasonMPM/fabdash + + +--- + +## Table of Contents + +- [Overview](#overview) +- [Tech Stack](#tech-stack) +- [Project Structure](#project-structure) +- [Features](#features) +- [Interaction Reference](#interaction-reference) +- [Keyboard Shortcuts](#keyboard-shortcuts) +- [API Reference](#api-reference) +- [Component Architecture](#component-architecture) +- [Unraid Installation](#unraid-installation) +- [Adding Your Logo](#adding-your-logo) +- [Updating FabDash on Unraid](#updating-fabdash-on-unraid) +- [Local Development](#local-development) +- [Environment Variables](#environment-variables) +- [Database Schema](#database-schema) +- [Roadmap](#roadmap) + +--- + +## Overview + +FabDash is a self-hosted, full-stack project management dashboard built for fabrication teams. It features a large interactive calendar, multi-deliverable project tracking, drag-and-drop scheduling, a per-project Focus View timeline, a redesigned workload heatmap with per-status color-coded grids, an agenda panel, right-click context menus, keyboard shortcuts, and a collapsible branded sidebar — all wrapped in a dark/gold UI and deployed as a single Docker container with no external dependencies. + +--- + +## Tech Stack + +### Frontend + +| Package | Version | Purpose | +|---|---|---| +| React | ^18.3.1 | UI framework | +| Vite | ^5.4.11 | Build tool and dev server | +| Tailwind CSS | ^3.4.15 | Utility-first styling | +| @fullcalendar/core | 6.1.15 | FullCalendar core (pinned — version must match all FC packages) | +| @fullcalendar/react | 6.1.15 | Calendar component | +| @fullcalendar/daygrid | 6.1.15 | Month/week grid view | +| @fullcalendar/timegrid | 6.1.15 | Time-slot view | + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/family-planner.md b/.source-references/references-only/reference vault/memory/projects/family-planner.md new file mode 100644 index 0000000..7b8c204 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/family-planner.md @@ -0,0 +1,82 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/family-planner +repo_url: https://git.alwisp.com/jason/family-planner +language: TypeScript +branch: main +tags: [repo, jason] +updated: 2026-05-29 +--- + +# family-planner + +**Repository:** [jason/family-planner](https://git.alwisp.com/jason/family-planner) · branch `main` · TypeScript + +## Summary + +Self-hosted family dashboard for always-on displays — calendars, chores, shopping, meals, message board, countdowns, and photo screensaver in one Docker container + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +_Source: PROJECT.md_ + +# Family Planner — Project Reference + +A self-hosted family dashboard designed for always-on display (wall tablet, TV, Unraid server). Manages calendars, chores, shopping, meals, a message board, countdowns, and a photo screensaver — all in one Docker container with zero external services required. + +--- + +## Tech Stack + +| Layer | Technology | +|---|---| +| **Runtime** | Node.js 22, Docker (Alpine) | +| **Backend** | Express 4, TypeScript 5 | +| **Database** | Node.js built-in SQLite (`node:sqlite`), WAL mode | +| **File uploads** | Multer | +| **Frontend** | React 18, TypeScript 5, Vite 5 | +| **Styling** | Tailwind CSS 3, CSS custom properties (theme tokens) | +| **Animation** | Framer Motion 11 | +| **State / data** | TanStack Query 5, Zustand 4 | +| **Routing** | React Router 6 | +| **Icons** | Lucide React | +| **Date utils** | date-fns 3 | +| **Package manager** | pnpm (workspaces monorepo) | +| **CI/CD** | Gitea Actions → Docker build & push to private registry | +| **Deployment target** | Unraid (Community Applications / CLI install) | + +--- + +## Repository Structure + +``` +family-planner/ +├── apps/ +│ ├── client/ # React frontend +│ │ └── src/ +│ │ ├── components/ +│ │ │ ├── layout/ +│ │ │ │ └── AppShell.tsx # Sidebar, mobile drawer, page wrapper +│ │ │ ├── screensaver/ +│ │ │ │ └── Screensaver.tsx # Idle screensaver w/ Ken Burns slideshow +│ │ │ └── ui/ # Design-system primitives +│ │ │ ├── Avatar.tsx +│ │ │ ├── Badge.tsx +│ │ │ ├── Button.tsx +│ │ │ ├── Input.tsx +│ │ │ ├── Modal.tsx +│ │ │ ├── Select.tsx +│ │ │ ├── Textarea.tsx +│ │ │ └── ThemeToggle.tsx + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/inven.md b/.source-references/references-only/reference vault/memory/projects/inven.md new file mode 100644 index 0000000..9c6fb01 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/inven.md @@ -0,0 +1,82 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/inven +repo_url: https://git.alwisp.com/jason/inven +language: TypeScript +branch: main +tags: [repo, jason] +updated: 2026-05-29 +--- + +# inven + +**Repository:** [jason/inven](https://git.alwisp.com/jason/inven) · branch `main` · TypeScript + +## Summary + +Single-container inventory management for Unraid — parts, assemblies, BOMs, sales/purchase orders, invoicing, and a lightweight accounting journal on SQLite + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# Inven + +Inven is a single-container inventory management system for Unraid-style deployments. It manages stocked parts, assemblies built from parts, sales orders and shipping, purchase orders and restocking, customers, vendors, and a lightweight accounting journal on top of SQLite. + +## Current Scope + +- Parts and assemblies share one item master +- Assemblies support bill-of-material component definitions +- Inventory is tracked through a transaction ledger +- Sales orders can be created and shipped +- Purchase orders can be created and received +- Sales orders and purchase orders are created from relational inventory line selections +- Shipping and receiving are posted from relational order-line quantity controls +- Sales orders support partial shipments +- Purchase orders support partial receipts +- Invoices are generated from shipped sales orders +- Vendor bills are generated from received purchase orders +- Customer and vendor payments can clear receivables and payables +- Customer and vendor directories support the order flows +- Low-stock and suggested reorder views help drive replenishment +- A chart of accounts, account balances, and manual journals support the first accounting pass +- Built-in authentication protects the app with a bootstrap admin login + +## Stack + +- Next.js App Router +- TypeScript +- SQLite via `better-sqlite3` +- Single Docker container with Next.js standalone output + +## Quick Start + +1. Install Node.js 22 or newer. +2. Copy `.env.example` to `.env`. +3. Set `AUTH_SECRET`, `ADMIN_EMAIL`, and `ADMIN_PASSWORD`. +4. Update `DATABASE_PATH` if needed. +5. Install dependencies: + +```bash +npm install +``` + +6. Start the development server: + +```bash +npm run dev +``` + +7. Open `http://localhost:3000` and sign in with the bootstrap admin credentials. + + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/memer.md b/.source-references/references-only/reference vault/memory/projects/memer.md new file mode 100644 index 0000000..cb779c3 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/memer.md @@ -0,0 +1,79 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/memer +repo_url: https://git.alwisp.com/jason/memer +language: TypeScript +branch: main +tags: [repo, jason] +updated: 2026-05-29 +--- + +# memer + +**Repository:** [jason/memer](https://git.alwisp.com/jason/memer) · branch `main` · TypeScript + +## Summary + +Self-hosted meme gallery with quick-share for SMS and Telegram — Dockerized masonry grid with tag search, upload, and non-destructive image rescaling + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# Memer + +A self-hosted meme gallery with quick-share for text message and Telegram. Runs as a single Docker container, designed for Unraid. + +## Features + +- **Masonry gallery** — responsive, dark-themed grid +- **Upload** — drag & drop or click, supports JPG/PNG/GIF/WebP (up to 100 MB) +- **Tags** — organize with comma-separated tags, filter by tag in the gallery +- **Search** — full-text search across titles and descriptions +- **Quick share** — copy link, Telegram, SMS, or download from any card or detail view +- **Non-destructive rescale** — creates a child image at a new size without touching the original +- **Persistent** — SQLite database + image files on Docker volumes (easy to back up or export) + +## Quick Start + +```bash +cp .env.example .env +# Edit .env: set PUBLIC_URL to your domain +docker compose up --build -d +``` + +Open `http://localhost:3000`. + +## Unraid Setup + +1. In Unraid, go to **Docker > Add Container** (or use Community Applications). +2. Use the image `memer:latest` (build locally or push to a registry). +3. Map port **3000** to your desired host port. +4. Add two path mappings: + - `/data/images` → `/mnt/user/appdata/memer/images` + - `/data/db` → `/mnt/user/appdata/memer/db` +5. Set environment variable `PUBLIC_URL` to `https://meme.alwisp.com`. +6. Set up your reverse proxy (Nginx Proxy Manager, Swag, etc.) to point `meme.alwisp.com` → port 3000. + +## Environment Variables + +| Variable | Default | Description | +|---|---|---| +| `PUBLIC_URL` | `http://localhost:3000` | Used to build absolute share links | +| `PORT` | `3000` | Port the server listens on | +| `DATA_DIR` | `/data` | Root for images and DB inside the container | + +## API + +| Method | Path | Description | +|---|---|---| + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/mempalace.md b/.source-references/references-only/reference vault/memory/projects/mempalace.md new file mode 100644 index 0000000..7df7d25 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/mempalace.md @@ -0,0 +1,65 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/mempalace +repo_url: https://git.alwisp.com/jason/mempalace +language: Python +branch: main +tags: [repo, jason] +updated: 2026-05-29 +--- + +# mempalace + +**Repository:** [jason/mempalace](https://git.alwisp.com/jason/mempalace) · branch `main` · Python + +## Summary + +Server-mode fork of MemPalace — shared Docker container on Unraid so Claude Code, Codex, and MCP clients can share one persistent AI memory palace over LAN + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# MemPalace — server-mode fork + +Local-first AI memory, deployed as a shared service across machines. + +This is a personal fork of [MemPalace](https://github.com/MemPalace/mempalace) configured for **server-mode deployment**: MemPalace runs as a Docker container (typically on Unraid) and multiple AI tools — Claude Code, Codex, Antigravity, or any MCP-compatible client — connect to a single shared palace from any machine on the network. Auto-save hooks on each client push session transcripts to the server over HTTPS with bearer auth. + +The upstream project remains local-first by design. This fork makes one deliberate trade: data crosses the LAN to a user-controlled server instead of staying on the originating machine. Privacy, verbatim storage, no-cloud, and no-telemetry properties are otherwise unchanged. See [CLAUDE.md](CLAUDE.md) for the architectural reasoning. + +--- + +## What's in this fork + +``` + home LAN + ┌───────────────────────────────────┐ + │ Unraid (always on) │ + │ ┌────────────────────────────┐ │ + │ │ caddy :8443 (TLS + auth) │ │ + │ │ ├─ /sse → mcp-proxy │ │ + │ │ └─ /ingest → ingest API │ │ + │ │ mempalace (single process) │ │ + │ │ ├─ mcp-proxy :8765 │ │ + │ │ └─ ingest :8766 │ │ + │ └────────────────────────────┘ │ + └───────────────────────────────────┘ + │ │ │ + ┌────┴───┐ ┌────┴───┐ ┌────┴─────┐ + │ Claude │ │ Codex │ │ Antigrav │ + └────────┘ └────────┘ └──────────┘ +``` + +* **One palace, many clients.** Search and write target the same ChromaDB index regardless of which machine you're on. +* **Single bearer token gates everything.** Caddy sidecar terminates TLS and enforces `Authorization: Bearer ` at the edge. + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/mrp-qrcode.md b/.source-references/references-only/reference vault/memory/projects/mrp-qrcode.md new file mode 100644 index 0000000..db7e018 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/mrp-qrcode.md @@ -0,0 +1,52 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/mrp-qrcode +repo_url: https://git.alwisp.com/jason/mrp-qrcode +language: TypeScript +branch: main +tags: [repo, jason] +updated: 2026-05-29 +--- + +# mrp-qrcode + +**Repository:** [jason/mrp-qrcode](https://git.alwisp.com/jason/mrp-qrcode) · branch `main` · TypeScript + +## Summary + +MRP QR Code System — fabrication shop tracker with printable QR traveler cards, phone-based operator scan flow, PDF generation, and in-browser STEP viewer + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# MRP QR Code System + +A single-container, self-hosted Manufacturing Resource Planning (MRP) app built around printable QR-coded traveler cards. Designed for small fabrication shops running on an Unraid server with phone-based operators. + +## Status + +Shipped (see [`docs/BUILD-PLAN.md`](docs/BUILD-PLAN.md)): steps 1, 2, 3, 4, 5, 6, 8. + +- **1.** Scaffold + auth (admin email/password, operator name/4-digit PIN with 12 h device session, PIN lockout, audited sessions). +- **2.** Admin CRUD (users, machines, operation templates, projects / assemblies / parts) with content-addressed STEP / PDF / DXF / SVG file uploads. +- **3.** Operation authoring with per-operation QR tokens (192-bit, base64url). +- **4.** Operator scan flow — phone scan resolves `/op/scan/`, single-claim enforced at DB level, Start / Pause / Done with inline QC for steps that require it, TimeLog rows for every claim. +- **5.** PDF traveler generation — per-operation card + per-part cover sheet with the full operation list and file manifest. Printed via `pdf-lib` (no native deps). +- **6.** Fasteners + purchase orders — per-project BOM of fasteners with unresolved-need rollups, PO lifecycle (`draft → sent → partial → received`, or `cancelled`), per-line receipt entry with auto-advance, and vendor-ready PDF downloads. +- **8.** In-browser STEP viewer — OpenCascade (WASM, via `occt-import-js`) parses STEP/STP, `three.js` renders with OrbitControls. Thumbnails are captured from the first rendered frame, uploaded to the content-addressed file store, and displayed on the assembly parts list. No native deps, no server-side GL. + +Planned (not yet shipped): dashboard (step 7) → dedicated QC operations (9) → OpenAPI docs + backups (10). + +## Core concepts + + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/mrp.md b/.source-references/references-only/reference vault/memory/projects/mrp.md new file mode 100644 index 0000000..238c2fb --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/mrp.md @@ -0,0 +1,56 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/mrp +repo_url: https://git.alwisp.com/jason/mrp +language: TypeScript +branch: master +tags: [repo, jason] +updated: 2026-05-29 +--- + +# mrp + +**Repository:** [jason/mrp](https://git.alwisp.com/jason/mrp) · branch `master` · TypeScript + +## Summary + +CODEXIUM: modular Manufacturing Resource Planning platform — React, Express, Prisma, and SQLite with full CRM, inventory, BOM, and RBAC in one Docker container + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# CODEXIUM + +Foundation release for a modular Manufacturing Resource Planning platform built with React, Express, Prisma, SQLite, and a single-container Docker deployment. + +## Documentation Maintenance + +- Keep [CHANGELOG.md](D:/CODING/mrp-codex/CHANGELOG.md) updated for shipped features, workflow changes, and notable operational updates. +- Keep [README.md](D:/CODING/mrp-codex/README.md), [INSTRUCTIONS.md](D:/CODING/mrp-codex/INSTRUCTIONS.md), [STRUCTURE.md](D:/CODING/mrp-codex/STRUCTURE.md), [ROADMAP.md](D:/CODING/mrp-codex/ROADMAP.md), [SHIPPED.md](D:/CODING/mrp-codex/SHIPPED.md), and [UNRAID.md](D:/CODING/mrp-codex/UNRAID.md) aligned when changes affect their scope. + +Current foundation scope includes: + +- authentication and RBAC +- company branding and theme settings, including startup brand-theme hydration across refresh +- CRM customers and vendors with create/edit/detail workflows +- CRM search, filtering, status tagging, and reseller hierarchy +- CRM contact history, account contacts, and shared attachments +- inventory item master, BOM, warehouse, stock-location, and stock-transaction flows +- inventory transfers, reservations, and available-stock visibility +- inventory SKU master builder with family-scoped sequence generation and branch-aware taxonomy management +- staged thumbnail image attachment on inventory item create/edit workflows, with detail-page thumbnail display +- sales quotes and sales orders with searchable customer and SKU entry +- sales approvals, approval stamps, automatic revision history, and revision comparison on quotes and sales orders +- purchase orders with searchable vendor and SKU entry, restricted to purchasable inventory items +- purchase-order revision history and revision comparison across commercial and receipt changes + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/nyaa-crawler.md b/.source-references/references-only/reference vault/memory/projects/nyaa-crawler.md new file mode 100644 index 0000000..82e4793 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/nyaa-crawler.md @@ -0,0 +1,96 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/nyaa-crawler +repo_url: https://git.alwisp.com/jason/nyaa-crawler +language: TypeScript +branch: main +tags: [repo, jason] +updated: 2026-05-29 +--- + +# nyaa-crawler + +**Repository:** [jason/nyaa-crawler](https://git.alwisp.com/jason/nyaa-crawler) · branch `main` · TypeScript + +## Summary + +Dockerized Nyaa.si anime torrent crawler — tracks shows, polls RSS for new episodes, and auto-downloads torrent files with a dark-themed web UI and SQLite persistence + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# nyaa-crawler + +A dockerized torrent crawler and downloader for [Nyaa.si](https://nyaa.si). Track anime shows, poll for new episodes via RSS, and automatically download `.torrent` files to a host-mounted directory. + +## Features + +- Search Nyaa.si and add shows to a watch list +- Automatic polling for new episodes (configurable interval, default 15 min) +- Auto-downloads `.torrent` files to a mapped host directory +- Track episode status: pending, auto-downloaded, or manually marked +- Bulk-mark episodes as already downloaded +- Minimal dark-themed web UI +- SQLite persistence — easy to back up and migrate +- Unraid-friendly Docker container + +## Stack + +- **Backend**: Node.js + TypeScript + Express +- **Frontend**: React + Vite +- **Database**: SQLite (`better-sqlite3`) +- **Scheduler**: `node-cron` +- **Nyaa integration**: RSS via `fast-xml-parser` + +## Quick Start (Docker) + +```bash +docker compose up -d +``` + +Open `http://localhost:8082` in your browser. + +## Quick Start (Development) + +```bash +npm install +npm run dev +``` + +- Client dev server: `http://localhost:5173` (proxies `/api` to `:3000`) +- API server: `http://localhost:3000` + +## Environment Variables + +| Variable | Default | Description | +|---|---|---| +| `PORT` | `3000` | HTTP port | +| `POLL_INTERVAL_SECONDS` | `900` | Polling frequency (min 60) | +| `TORRENT_OUTPUT_DIR` | `./data/torrents` | Where `.torrent` files are saved | +| `DATABASE_PATH` | `./data/db.sqlite` | SQLite database path | + +## Unraid Deployment + +```yaml +services: + nyaa-watcher: + image: your-registry/nyaa-watcher:latest + container_name: nyaa-watcher + restart: unless-stopped + environment: + - PORT=3000 + - POLL_INTERVAL_SECONDS=900 + - TORRENT_OUTPUT_DIR=/data/torrents + - DATABASE_PATH=/data/db.sqlite + volumes: + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/obsidian-memory-plugin.md b/.source-references/references-only/reference vault/memory/projects/obsidian-memory-plugin.md new file mode 100644 index 0000000..458dbf5 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/obsidian-memory-plugin.md @@ -0,0 +1,128 @@ +--- +type: project +status: active +tags: [obsidian, cowork, plugin, memory] +updated: 2026-05-27 +--- + +# obsidian-memory Plugin + +Claude Cowork plugin that uses Jason's Obsidian vault at 10.2.0.2 as persistent memory across sessions. + +## Current status + +Plugin built and installed. Vault bootstrapped 2026-05-27. Ready for daily use — memory accumulates as sessions run. + +## Key decisions + +- No MCP server — direct REST calls via bash/curl (simpler, fully portable in a single .plugin file) +- API key and server hardcoded (personal plugin, not for distribution) +- Uses `-k` flag for SSL (Obsidian Local REST API uses a self-signed cert) +- Server: `https://10.2.0.2:27124` +- API key: stored in skill, not to be redistributed +- Vault layout roots at `Projects/agents/` — index → profile → memory subdirs + +## Architecture + +``` +obsidian-memory.plugin +├── .claude-plugin/plugin.json +├── skills/obsidian-memory/ +│ ├── SKILL.md ← load/write/log instructions + curl patterns +│ └── references/ +│ ├── api-reference.md ← all curl endpoint patterns +│ ├── vault-layout.md ← frontmatter conventions + folder map +│ ├── bootstrap.md ← first-run setup procedure +│ └── session-log-template.md +└── README.md +``` + +## Vault layout + +``` +Projects/agents/ +├── README.md +├── memory/ +│ ├── profile.md +│ ├── inbox.md +│ ├── projects/.md +│ ├── sessions/YYYY-MM-DD-.md +│ ├── people/.md +│ └── decisions/YYYY-MM-DD-.md +``` + +## Open threads + +- [ ] Populate profile.md as facts emerge in conversations +- [ ] Consider adding a decisions file for major project choices + +## Log + +- 2026-05-27: Plugin built in Cowork session. Vault bootstrapped. First session logged. + +## Known issues + +### PATCH with `Target-Type: heading` returns invalid-target (2026-05-28) + +**Symptom:** Every `PATCH` request with `Operation: append|replace`, `Target-Type: heading`, and a `Target:` header (e.g. `Target: Current status`) returns: + +``` +HTTP 400 +{ "message": "The patch you provided could not be applied to the target content.\ninvalid-target", "errorCode": 40080 } +``` + +This happens on **all files tested** including freshly-fetched profile.md and project files with confirmed valid heading text. The documented example from `references/api-reference.md` ("Replace a heading's content entirely") reproduces the failure exactly. + +Reading a heading via URL path (`/vault/path/file.md/heading/Heading%20Name`) **also** returns `404 Not Found` even when the heading clearly exists in the file body — so the failure is in the heading-resolution layer, not the patch-apply layer. + +**Workaround:** Use `POST` (append-to-EOF) and `PUT` (full overwrite) instead. The skill's main flow already documents POST as the default for additive entries, so this only matters when you need targeted section editing (e.g. "replace Current status" for a project file). + +**Impact:** Cannot do surgical section replacement. The project file for `unifi-access-dashboard.md` ended up with the new content appended to the bottom instead of replacing "Current status" inline — readable but less tidy. + +**To investigate:** + +- [ ] Check installed Local REST API plugin version on the vault (Obsidian → Settings → Community plugins) +- [ ] Compare against the [coddingtonbear/obsidian-local-rest-api](https://github.com/coddingtonbear/obsidian-local-rest-api) release notes for PATCH-heading regressions +- [ ] If recent, try downgrading; if old, try upgrading +- [ ] Try with explicit `Target-Delimiter` header (some versions need it for top-level headings) +- [ ] Verify the file is using LF line endings — CRLF can break heading parsing in some plugin versions + +## Log + +- 2026-05-28: Discovered PATCH-heading bug during the unifi-access-dashboard memory update. Logged under Known issues; working around with POST/PUT. + +### Retest after plugin upgrade 3.6 → 4.1.1 (2026-05-28) + +**Still broken.** Both failure modes reproduce identically after the upgrade: + +| Test | Result | +|---|---| +| `PATCH` w/ `Target-Type: heading`, `Target: Communication preferences` | HTTP 400, `invalid-target` | +| `PATCH` w/ `Target-Type: heading`, `Target: Role` (single word, no spaces) | HTTP 400, `invalid-target` | +| `PATCH` w/ `Target-Type: heading`, `Target: Communication%20preferences` (URL-encoded) | HTTP 400, `invalid-target` | +| `GET /vault/.../profile.md/heading/Role` (URL-path heading read) | HTTP 404, `Not Found` | +| `GET /vault/.../profile.md` (bare file read — sanity) | HTTP 200 ✓ | +| **`PATCH` w/ `Target-Type: frontmatter`, `Target: updated`** | **HTTP 200 ✓** | + +**Narrowed diagnosis:** The PATCH route is healthy — `Target-Type: frontmatter` works perfectly. Only the **heading resolver** is broken. The same resolver is shared between the heading-target PATCH path and the URL-path `/heading/...` read path (both 404 on valid headings), which is consistent with a single bug in heading lookup. + +**Ruled out:** + +- ~~Plugin version (3.6 was old)~~ — 4.1.1 has the same bug +- ~~Spaces in heading text~~ — single-word "Role" also fails +- ~~URL encoding of `Target:` header~~ — both raw and `%20`-encoded fail +- ~~Broken PATCH route generally~~ — frontmatter target works + +**Likely culprits (narrower now):** + +- [ ] CRLF vs LF line endings in vault files — heading parser may require LF. Files written by curl from this skill use LF, but files edited in Obsidian on Windows might get CRLF. +- [ ] Unicode BOM at file start +- [ ] An option in the plugin settings UI that toggles heading-mode patches +- [ ] An upstream bug — worth opening an issue at `coddingtonbear/obsidian-local-rest-api` with this exact reproducer (it's small and easy to verify) + +**Workarounds (in order of preference):** + +1. For metadata: `Target-Type: frontmatter` works — use it for `updated`, `status`, `tags`. +2. For additive section content: `POST` (append to EOF) — already the skill's documented default. +3. For surgical section replacement: read the file, modify in code, `PUT` the whole thing back. Heavy-handed but reliable. +- 2026-05-28: Plugin upgraded 3.6 → 4.1.1 to fix the PATCH-heading bug. Retest shows the bug **persists** in 4.1.1. Narrowed: `Target-Type: frontmatter` works, only `Target-Type: heading` (and the URL-path `/heading/...` read) is broken. Likely a heading-resolver bug. Workaround unchanged: POST/PUT/frontmatter-PATCH only. diff --git a/.source-references/references-only/reference vault/memory/projects/pnger.md b/.source-references/references-only/reference vault/memory/projects/pnger.md new file mode 100644 index 0000000..f229d2d --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/pnger.md @@ -0,0 +1,82 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/pnger +repo_url: https://git.alwisp.com/jason/pnger +language: Svelte +branch: main +tags: + - repo + - jason + - alwisp +updated: 2026-05-29 +--- + +# pnger + +**Repository:** [jason/pnger](https://git.alwisp.com/jason/pnger) · branch `main` · Svelte + +## Summary + +Modern PNG editor & resizer with live preview, drag & drop, smart presets, keyboard shortcuts, and dark/light themes. TypeScript + Svelte + Sharp. Deployed on Unraid. + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# PNGer - Modern PNG Editor & Resizer + +A sleek, modern PNG editor and resizer with **live preview**, **drag & drop**, **smart presets**, **keyboard shortcuts**, and **dark/light mode theming**. Built with TypeScript and optimized for deployment as a single Docker container. + +## ✨ Features + +- **🎨 Modern UI**: Beautiful dark/light mode for inspecting transparency. +- **⚡ Live Preview**: Instant side-by-side comparison with file size analysis. +- **🚀 Efficiency**: Drag & Drop upload, clipboard paste (`Ctrl+V`), and smart presets. +- **🖼️ Precision**: Control width, height, quality, and crop positions (9 modes). +- **📦 Reliable Deployment**: Multi-stage Docker build optimized for Unraid and Gitea. + +## 🚀 Quick Start + +### Docker/Unraid Deployment +1. **Clone & Build**: + ```bash + git clone https://git.alwisp.com/jason/pnger.git + cd pnger + docker build -t pnger:latest . + ``` +2. **Run**: + ```bash + docker compose up -d + ``` +3. **Access**: `http://localhost:8080` (or your Unraid IP) + +### Local Development +1. **Install & Run Backend**: `cd backend && npm install && npm run dev` +2. **Install & Run Frontend**: `cd frontend && npm install && npm run dev` +3. **Access**: `http://localhost:5173` + +## 📚 Documentation + +For more detailed information, please refer to: +- **[INSTRUCTIONS.md](./INSTRUCTIONS.md)**: Technical architecture, development setup, code standards, and troubleshooting. +- **[ROADMAP.md](./ROADMAP.md)**: Project history, sprint updates, and future feature plans. + +## ⌨️ Keyboard Shortcuts + +- `Ctrl+V`: Paste image from clipboard +- `Enter`: Download (when input not focused) +- `?`: Show shortcuts help +- `Esc`: Close dialogs + +--- + +**License**: MIT +**Repository**: [https://git.alwisp.com/jason/pnger](https://git.alwisp.com/jason/pnger) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/pos.md b/.source-references/references-only/reference vault/memory/projects/pos.md new file mode 100644 index 0000000..98d4ecd --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/pos.md @@ -0,0 +1,115 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/pos +repo_url: https://git.alwisp.com/jason/pos +language: TypeScript +branch: main +tags: + - repo + - jason + - alwisp +updated: 2026-05-29 +--- + +# pos + +**Repository:** [jason/pos](https://git.alwisp.com/jason/pos) · branch `main` · TypeScript + +## Summary + +Full-stack TypeScript point-of-sale system — Android POS frontend, Node/Express API, and React admin UI packaged in a single Docker container + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# README.md + +## Overview + +This project is a full-stack TypeScript point-of-sale (POS) system: an Android POS frontend, a Node/Express API backend, and a React admin UI, all packaged in a **single Docker container**. + +The backend exposes REST APIs for the Android app and serves the React admin UI for vendor configuration and reporting. + +*** + +## Tech Stack + +- Node.js + TypeScript (Express or Fastify) +- React + TypeScript (SPA) +- SQL database (PostgreSQL in production; SQLite acceptable for local/demo) +- Docker (single container for API + admin UI) + +*** + +## Project Structure + +Example layout (subject to refinement): + +- `server/` – Node/TypeScript backend (Express/Fastify, Prisma, migrations) +- `client/` – React/TypeScript admin UI +- `android/` – Android POS app (separate repo or module) +- `Dockerfile` – single-image build for backend + admin +- `docker-compose.yml` – optional local DB wiring +- `AGENTS.md`, `INSTRUCTIONS.md`, `ROADMAP.md` – agent and project docs + +*** + +## Prerequisites + +For local (non-Docker) runs: + +- Node.js 20+ installed +- npm or pnpm +- PostgreSQL (or SQLite if configured) + +For Docker runs: + +- Docker Engine (and optionally Docker Compose) + +*** + +## Environment Variables + +Backend expects: + +- `PORT` – HTTP port (default: 8080) +- `NODE_ENV` – `development` or `production` +- `DATABASE_URL` – connection string (e.g., Postgres) +- `JWT_SECRET` – secret for JWT signing +- `LOG_LEVEL` – optional (`info`, `debug`, etc.) + +Document any additional env vars you introduce in this section. + +*** + +## Local Development (Without Docker) + +Backend: + +```bash +# from /server +npm install +npm run dev # or equivalent, e.g. ts-node-dev / nodemon +``` + +Admin UI: + +```bash +# from /client +npm install +npm run dev # Vite/CRA dev server +``` + +You can either: + + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/qrknit.md b/.source-references/references-only/reference vault/memory/projects/qrknit.md new file mode 100644 index 0000000..05d2a0a --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/qrknit.md @@ -0,0 +1,57 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: qrknit/qrknit +repo_url: https://git.alwisp.com/qrknit/qrknit +language: HTML +branch: master +tags: [repo, qrknit] +updated: 2026-05-29 +--- + +# qrknit + +**Repository:** [qrknit/qrknit](https://git.alwisp.com/qrknit/qrknit) · branch `master` · HTML + +## Summary + +QRKnit: commercial QR code generator and URL shortener — create, manage, and track branded QR codes and short links + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# QRknit — URL Shortener & QR Code Generator + +A managed URL shortener with QR code generation, deep click analytics, and tag-based link organization. + +- **Multi-user** — admin account seeded from env vars; admin can create/delete/manage accounts via the UI +- **Per-user isolation** — each user sees only their own links and tags; admin has its own isolated workspace separate from all other accounts +- **Organizations** — group users into orgs that share link/tag visibility and pool usage quotas under a shared plan +- **Plan tiers** — Admin / Free / Starter / Pro / Team with enforced limits on active links, monthly clicks, and analytics history window; org members inherit their org's plan +- **Scoped tags** — tags are owned by the user who creates them; org members share a tag namespace, solo users and admins each have their own isolated namespace +- **Deep analytics** — daily charts, referrer/device/browser/country breakdowns, hourly 7×24 heatmap, raw click CSV export +- **Private instance** — Pro and Team plans include a dedicated private deployment on your own infrastructure + +--- + +## 🗺 Feature Map + +### Shipped + +| Feature area | What's included | +|---|---| +| **Short links** | Random & custom codes, link expiry, pinned links, one-click copy, auto-fetch page title | +| **QR codes** | QR generation for any link or URL, logo overlay, dot-shape presets, inline thumbnail, copy to clipboard | +| **Analytics** | Per-link daily click charts, referrer / device / browser / country breakdowns, hourly 7×24 heatmap, raw click CSV export | +| **Tags** | Tag links for filtering; tags are scoped per user — org members share a namespace, solo users and admins each have their own | +| **Bulk tools** | Bulk delete, bulk tag, bulk expire; CSV import & export | + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/rack-planner.md b/.source-references/references-only/reference vault/memory/projects/rack-planner.md new file mode 100644 index 0000000..aa58ed4 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/rack-planner.md @@ -0,0 +1,78 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/rack-planner +repo_url: https://git.alwisp.com/jason/rack-planner +language: TypeScript +branch: main +tags: [repo, jason] +updated: 2026-05-29 +--- + +# rack-planner + +**Repository:** [jason/rack-planner](https://git.alwisp.com/jason/rack-planner) · branch `main` · TypeScript + +## Summary + +RackMapper: self-hosted dark-mode web app for visualizing and managing network rack infrastructure — drag-and-drop rack planner and service dependency mapper for Unraid + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# RackMapper + +A self-hosted, dark-mode web app for visualising and managing network rack infrastructure. Built for Unraid / Docker single-container deployment. + +## Features + +### Rack Planner (`/rack`) +- Drag-and-drop module placement from a device palette onto U-slots +- Drag modules between racks or reorder racks via header grip +- Resize modules by dragging the bottom handle +- Click any module to edit name, IP, manufacturer, model, notes, uSize +- Port indicator dots — click any dot to open the port configuration modal + - Set mode (Access / Trunk / Hybrid), native VLAN, tagged VLANs + - Quick-create VLANs without leaving the modal +- Export the full rack view as PNG + +### Service Mapper (`/map`) +- React Flow canvas for mapping service dependencies and traffic flows +- Right-click canvas → add any node type at cursor position +- Right-click node → Edit, Duplicate, Delete +- Right-click edge → Toggle animation, change edge type, Delete +- Double-click a node → edit label, accent colour, logical IP/Port, and rack module link +- Logical Address mapping — assign IP and Port to any node type via metadata (stored as JSON) +- Persistent storage — all node details and logical addresses are saved to the SQLite database +- Auto-populate nodes from all rack modules ("Import Rack" button) +- Connect nodes by dragging from handles; Delete key removes selected items +- Minimap, zoom controls, snap-to-grid (15px), PNG export + +### VLAN Management (`/vlans`) +- Create, edit, and delete VLANs with ID, name, description, and colour +- VLANs defined here are available in all port configuration modals + +--- + +## Quick Start (Docker Compose) + +**1. Create a `docker-compose.yml`:** + +```yaml +version: '3.8' +services: + rackmapper: + image: rackmapper + build: . + container_name: rackmapper + ports: + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/stepview.md b/.source-references/references-only/reference vault/memory/projects/stepview.md new file mode 100644 index 0000000..3bebca4 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/stepview.md @@ -0,0 +1,87 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/stepview +repo_url: https://git.alwisp.com/jason/stepview +language: TypeScript +branch: main +tags: + - repo + - jason + - mpm +updated: 2026-05-29 +--- + +# stepview + +**Repository:** [jason/stepview](https://git.alwisp.com/jason/stepview) · branch `main` · TypeScript + +## Summary + +StepView: self-hosted in-browser 3D STEP file viewer — renders .step/.stp files via OpenCascade (WASM) and three.js, deployed as a Docker container on Unraid + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +_Source: INSTALL.md_ + +# StepView — Unraid Installation Guide + +This guide covers the full deployment path: building the Docker image via the Gitea CI runner, then installing and configuring the container through the Unraid Docker GUI. + +--- + +## Table of Contents + +1. [Prerequisites](#1-prerequisites) +2. [Build Pipeline — Gitea Actions](#2-build-pipeline--gitea-actions) +3. [Unraid — Add the Registry](#3-unraid--add-the-registry) +4. [Unraid — Install the Container](#4-unraid--install-the-container) +5. [Environment Variables Reference](#5-environment-variables-reference) +6. [Volume Paths Reference](#6-volume-paths-reference) +7. [First-Run Steps](#7-first-run-steps) +8. [Upgrading](#8-upgrading) +9. [Backups](#9-backups) +10. [Troubleshooting](#10-troubleshooting) + +--- + +## 1. Prerequisites + +| Requirement | Notes | +|---|---| +| Unraid 6.12 or later | Earlier versions work but UI steps may differ slightly | +| Gitea instance | Any version with Actions support (1.19+) | +| Gitea Actions runner | Registered to your Gitea instance, labeled `ubuntu-latest` | +| Docker runner image | `catthehacker/ubuntu:act-latest` (already in your workflow) | +| `REGISTRY_USER` secret | Set in Gitea repo → Settings → Secrets | +| `REGISTRY_TOKEN` secret | An access token with `package:write` scope on `registry.alwisp.com` | + +--- + +## 2. Build Pipeline — Gitea Actions + +The workflow at `.gitea/workflows/docker-build.yml` runs automatically on every push to `main`. It builds the image and pushes it to: + +``` +registry.alwisp.com//stepview:latest +``` + +### Verify the secrets exist + +In your Gitea repository, go to **Settings → Secrets and Variables → Actions** and confirm both of these are set: + +| Secret name | Value | +|---|---| +| `REGISTRY_USER` | Your registry username | +| `REGISTRY_TOKEN` | Registry access token (read/write) | + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/storybid.md b/.source-references/references-only/reference vault/memory/projects/storybid.md new file mode 100644 index 0000000..64b46f7 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/storybid.md @@ -0,0 +1,95 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/storybid +repo_url: https://git.alwisp.com/jason/storybid +language: TypeScript +branch: main +tags: + - repo + - jason + - stroybook + - storybid +updated: 2026-05-29 +--- + +# storybid + +**Repository:** [jason/storybid](https://git.alwisp.com/jason/storybid) · branch `main` · TypeScript + +## Summary + +Self-hosted charity auction platform — live and silent auctions with offline-first PWA bidding, Socket.io real-time updates, Stripe payments, and SMS OTP auth + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# Storybid + +Self-hosted charity auction platform supporting live and silent auctions in the +same event, with offline-first PWA bidding and automatic LAN failover for +event-night resilience. + +## Stack + +| Layer | Choice | +|------------|---------------------------------------------| +| Client | React 18 + TypeScript + Vite + Tailwind | +| PWA/Offline| Workbox (vite-plugin-pwa) + Dexie/IndexedDB | +| Real-time | Socket.io | +| Server | Node.js + Express + TypeScript | +| ORM | Prisma | +| Database | PostgreSQL (SQLite optional for dev) | +| Cache/Queue| Redis (optional) | +| Auth | Email magic links + Twilio Verify SMS OTP | +| Payments | Stripe Payment Element / Payment Intents | +| Media | Local disk (multer) served as static files | +| Deploy | Docker Compose (Unraid / Linux VM) | + +## Quick Start (development) + +```bash +# 1. Clone and install +git clone +cd storybid +npm install + +# 2. Start DB + Redis +docker compose -f docker-compose.dev.yml up -d + +# 3. Configure environment +cp .env.example .env +# Edit .env with your Stripe, Twilio, and SMTP keys + +# 4. Migrate database and seed demo data +npm run db:migrate +npm run db:seed + +# 5. Start dev servers +npm run dev +# Client → http://localhost:5173 +# Server → http://localhost:3001 +``` + +## Production Deployment + +See [`ops/README.md`](./ops/README.md). + +## Event-Night Network + +See [`ops/unifi-dns.md`](./ops/unifi-dns.md) for UniFi local DNS setup and +WAN-failover testing. + +## Staff Runbook + +See [`event-runbook/preflight.md`](./event-runbook/preflight.md) for the + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/totalmcp.md b/.source-references/references-only/reference vault/memory/projects/totalmcp.md new file mode 100644 index 0000000..57a018c --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/totalmcp.md @@ -0,0 +1,88 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/totalmcp +repo_url: https://git.alwisp.com/jason/totalmcp +language: TypeScript +branch: main +tags: + - repo + - jason + - mcp + - ai +updated: 2026-05-29 +--- + +# totalmcp + +**Repository:** [jason/totalmcp](https://git.alwisp.com/jason/totalmcp) · branch `main` · TypeScript + +## Summary + +TotalMCP: unified MCP gateway for the ALPHA stack — hot-reloadable Dockerized server connecting Claude Code, Codex, and Antigravity to one stable endpoint on Unraid + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# totalmcp + +Unified MCP gateway for Jason's ALPHA stack. One Dockerized server, hot-reloadable plugin architecture, three agent clients (Claude Code, Codex, Antigravity) all connecting to one stable endpoint. + +- **Port:** `8811` +- **Static IP:** `10.2.0.35` (Unraid `br0`) +- **Registry:** `git.alwisp.com/jason/totalmcp` +- **Spec:** see [`PLAN.md`](PLAN.md) for the full architecture and phased roadmap +- **Service inventory:** see [`SERVICES.md`](SERVICES.md) for the catalog this gateway plugs into + +## Quick Start (local dev) + +```bash +cp .env.example .env # then fill in tokens +npm install +npm run prisma:generate +npm run dev # starts tsx watch on src/server.ts +``` + +Verify: + +```bash +curl http://localhost:8811/health +# → { "status": "ok", "version": "0.1.0", "plugins": 0, "enabled": [] } +``` + +## Build & run + +```bash +npm run build # tsc → dist/ +npm start # node dist/server.js +``` + +## Docker (local dev) + +```bash +docker compose up --build -d +docker compose logs -f totalmcp +``` + +## Unraid deployment + +Step-by-step GUI walkthrough — paths, variables, ports, network — lives in [`INSTALL-UNRAID.md`](INSTALL-UNRAID.md). Covers the full deploy at `10.2.0.35:8811` plus a minimal "Gitea-plugin-only" starter config. + +## Endpoints + +| Method | Path | Auth | Purpose | +|--------|-------------|----------|--------------------------------------| +| GET | `/health` | none | Liveness — used by Unraid HEALTHCHECK | +| GET | `/plugins` | bearer | Loaded plugin list + tool counts | +| POST | `/mcp` | bearer | Streamable HTTP — primary MCP transport | +| GET | `/mcp` | bearer | Streamable HTTP server-sent stream | + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/ui-tracker.md b/.source-references/references-only/reference vault/memory/projects/ui-tracker.md new file mode 100644 index 0000000..16cabfd --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/ui-tracker.md @@ -0,0 +1,87 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/ui-tracker +repo_url: https://git.alwisp.com/jason/ui-tracker +language: TypeScript +branch: main +tags: [repo, jason] +updated: 2026-05-29 +--- + +# ui-tracker + +**Repository:** [jason/ui-tracker](https://git.alwisp.com/jason/ui-tracker) · branch `main` · TypeScript + +## Summary + +Unifi Store stock monitor — watches store.ui.com for product restocks and sends Telegram alerts; single Docker container for Unraid with a React admin UI + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +_Source: PROJECT.md_ + +# UI Stock Tracker — Project Documentation + +**Status:** ✅ Complete and running +**Last updated:** 2026-03-29 + +--- + +## Purpose + +Monitors product pages on [store.ui.com](https://store.ui.com/us/en) for stock availability and sends a Telegram alert the moment a watched item comes back in stock. Runs as a single persistent Docker container on Unraid with a clean web UI for managing tracked products. + +--- + +## Stack + +| Layer | Technology | +|---|---| +| Frontend | React 18 + TypeScript, Vite, Lucide icons | +| Backend | Node.js 20 + TypeScript, Express | +| Database | SQLite via `better-sqlite3` (WAL mode) | +| Scraper | Puppeteer-core + system Chromium | +| Alerts | Telegram Bot API (direct HTTP) | +| Container | Single Docker container — nginx + Node.js managed by supervisord | +| Web server | nginx — serves frontend, proxies `/api/` to Node.js on port 3001 | + +--- + +## Container Architecture + +One container runs three processes via **supervisord**: + +``` +supervisord +├── nginx → serves React build on :8080, proxies /api/ → localhost:3001 +└── node → Express API, SQLite, Puppeteer scheduler, Telegram sender +``` + +The SQLite database is stored on a mounted volume at `/app/data/tracker.db` so it persists across rebuilds. + +--- + +## Key Features + +### Stock Detection +Puppeteer navigates to each product URL and waits for React hydration (2.5s delay), then scans all `` elements for exact text matches: +- `"Add to Cart"` → `in_stock` +- `"Sold Out"` → `sold_out` +- Neither found → `unknown` + +Product name is pulled from the `og:title` meta tag (with Ubiquiti store suffix stripped). Thumbnail is pulled from `og:image`. + +### Alert Logic +- Alert fires **once** when an item transitions to `in_stock` and `alert_sent = 0` + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/projects/unifi-access-dashboard.md b/.source-references/references-only/reference vault/memory/projects/unifi-access-dashboard.md new file mode 100644 index 0000000..b360fe2 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/unifi-access-dashboard.md @@ -0,0 +1,118 @@ +--- +type: project +status: active +tags: + - unifi + - access + - flask + - docker + - attendance + - multi-tenant + - mpm +updated: 2026-05-28 +--- + +# UniFi Access Badge-In Dashboard + +Repo: `F:\CODING\unifi-access-dashboard` · Unraid IP `10.2.0.11:8000` · Data at `/mnt/user/appdata/unifi-access-dashboard/`. See [[unraid-deployment]] for the deploy pipeline. + +Flask + SQLite app that ingests UniFi Access `access.door.unlock` webhooks and shows a daily attendance table (first/latest badge per person, ON TIME / LATE vs cutoff). + +## Current status + +Multi-controller support shipped 2026-05-28. The app now supports adding N UniFi Access controllers from the UI (⚙ Controllers button); each controller's webhook is auto-registered via the Access API. Driven by a client engagement where one on-site server has LAN reach to multiple Access controllers on a meshed network and wants a unified attendance view. + +## Architecture decisions + +- **Storage model**: tables `controllers`, `badge_events` (with `controller_id`), `user_cache` (composite PK `(controller_id, actor_id)`). The same physical person on two controllers shows as two rows distinguished by the Source column — no cross-controller identity merge (out of scope). +- **Webhook URLs**: `/api/unifi-access/` per-controller. Legacy `/api/unifi-access` kept as alias that routes to the oldest controller, so pre-multi-controller installs keep working without re-registering. +- **Auth & encryption**: explicitly NOT added. Jason picked LAN-only trust + plaintext tokens in SQLite. Filesystem permissions on `./data/dashboard.db` are the only thing protecting API tokens. Any future external exposure must put a reverse proxy with auth in front. +- **Webhook auto-registration**: adding a controller via UI POSTs to `/api/v1/developer/webhooks/endpoints` on that controller and stores the returned `secret` + `id`. Removing a controller calls Access to delete the webhook. +- **`DASHBOARD_BASE_URL` env var**: optional override for the URL the dashboard tells controllers to call back to. Defaults to `request.host_url` (the browser's origin when admin adds a controller). Set this if the controller can't reach that address. + +**Why:** these were active choices Jason made during the 2026-05-28 update — not omissions. Re-proposing auth or encryption needs new context, not a do-over. +**How to apply:** if future work touches admin endpoints or token storage, don't silently bolt on auth or encryption — flag it as a scope change first. + +## Configuration model + +- **Fresh installs**: leave `UNIFI_HOST`/`UNIFI_API_TOKEN`/`UNIFI_PORT`/`WEBHOOK_SECRET` blank in the Unraid template. Only set `TZ` and the `/data` mapping. Add every controller via the UI — that path auto-registers webhooks. +- **Upgrades from single-controller installs**: leave the env vars alone. Migration on first boot seeds a "Default" controller from them and backfills existing `badge_events` rows. After verifying the UI shows Default, the env vars are dead weight and can be removed, but keeping them is harmless and defensive (re-seeds if `./data` is wiped). +- **Gotcha**: a seeded Default controller has no `webhook_id` stored (the webhook was registered manually before the multi-controller refactor). If someone removes Default in the UI and re-adds via the form, the OLD webhook on the Access side is not deleted (we don't know its id) and the NEW one is added on top — every badge event arrives twice until the old webhook is manually deleted on the Access controller. + +## Operational details + +- User-cache auto-sync runs hourly (`scheduler.add_job(sync_all_controllers, "interval", hours=1)`). Badge events themselves are real-time via webhook — this interval only affects how fast renamed users show new display names. +- HMAC-SHA256 signature verification is per-controller (each controller's `webhook_secret` is enforced on its own endpoint). A controller with an empty stored secret accepts unsigned posts — intentional for LAN-trust mode. +- Cutoff comparison is string-based on `HH:MM:SS`; cutoff input is sanitized to `HH:MM` and compared as `<= "{cutoff}:59"`. Don't change this to time-object parsing without verifying the SQL still groups correctly. + +--- + +## Update 2026-05-28 (pm): tenant filtering + identity merging + +Same-day follow-up to the multi-controller ship. Two related features added together. The earlier "Architecture decisions" note that cross-controller identity merging was out of scope is **superseded** — it's now in scope and shipped. + +### Tenant filtering + +- New column `user_cache.filtered INTEGER NOT NULL DEFAULT 0`. Additive migration via `ALTER TABLE` for existing DBs. +- Sync code at `app.py:194-203` already only updates `full_name`/`updated_at` on conflict, so the filter flag survives every hourly sync naturally — no defensive logic needed. +- `/api/first-badge-status` excludes filtered actors by default; pass `?include_filtered=1` to include them (UI uses this for the "Show filtered" toggle that dims filtered rows and tags them with a FILTERED pill). +- Webhook ingest is **unchanged** — filtering is purely display-time. Unfiltering instantly restores history with no gaps. +- New endpoints: `GET /api/users`, `PATCH /api/users//` (`{filtered: bool}`). The PATCH upserts a placeholder cache row if the actor isn't yet known so the flag has somewhere to live (covers the "Unknown user" case). + +### Identity merging across controllers + +Driver: same physical person on two controllers gets two UUIDs, so badging into Controller A at 8:45 and Controller B at 9:15 produces one ON TIME row + one LATE row even though arrival was 8:45. Merging fixes this. + +**Schema** — two new tables, both purely additive: +```sql +CREATE TABLE persons ( + id TEXT PRIMARY KEY, + display_name TEXT NOT NULL, + filtered INTEGER NOT NULL DEFAULT 0, + created_at TEXT NOT NULL +); +CREATE TABLE person_members ( + person_id TEXT NOT NULL, + controller_id TEXT NOT NULL, + actor_id TEXT NOT NULL, + PRIMARY KEY (controller_id, actor_id), -- one actor → one person + FOREIGN KEY (person_id) REFERENCES persons(id) ON DELETE CASCADE +); +``` + +**Why two tables, not a `merge_group` column on `user_cache`:** chosen for headroom. `user_cache` is a sync cache (overwritten from UniFi); `persons` is the editorial layer where the user owns display name, filter flag, and any future per-person fields (notes, department, photo). Picked Option A from the design brainstorm; rejected Options B (shared group_id column) and C (self-referential `merged_into`). + +**Query change** in `/api/first-badge-status`: groups by `COALESCE(pm.person_id, b.controller_id || '|' || b.actor_id)` so unmerged rows still group by `(controller, actor)`. Sources column becomes a `GROUP_CONCAT(DISTINCT c.name)` list. Filter promotes via `COALESCE(p.filtered, u.filtered, 0)`. + +**Hide button dispatch**: if the row is merged, UI calls `PATCH /api/persons/` with `{filtered: bool}`; if not, it calls `PATCH /api/users//` (old behavior). + +**Filter-on-unmerge decision**: when a member is split off from a merged person, the member returns **unfiltered**. Person-level filter dies with the merge. Picked for simpler mental model — re-hide individually if needed. Alternative (inherit filter on split) was rejected as surprising. + +**Auto-suggestions** (`GET /api/persons/suggestions`): groups `user_cache` rows by exact-name match (case-insensitive, trimmed, excluding "User xxxxx" placeholders) where the same name spans ≥2 distinct controllers and none of the members are already part of a person. UI shows these at the top of the People modal with a one-click confirm per suggestion — never auto-applied. + +**UI**: per-row Merge button (becomes "Manage" on already-merged rows, opens the People modal scrolled to that person); a new "👥 People" header button opens a modal with suggested merges + management actions (Rename, Split off, Dissolve). Merged rows in the attendance table get multiple Source chips and a "MERGED" pill. + +### New endpoints (full list) + +- `GET /api/users` — list cached actors with filter flag +- `PATCH /api/users//` — hide/unhide one actor +- `GET /api/persons` — list merged people with members +- `POST /api/persons` — create with `{display_name, members:[{controller_id, actor_id},...]}` +- `PATCH /api/persons/` — rename or toggle filtered +- `DELETE /api/persons/` — dissolve +- `POST /api/persons//members` — add a member +- `DELETE /api/persons//members//` — split off (auto-dissolves on last member) +- `GET /api/persons/suggestions` — exact-name matches across controllers + +### Sharp edges to remember + +- **Source chip is now a list per row.** Anything that consumed `row.source` as a single string still works (we kept the first chip there for backwards compat), but the new field is `row.sources` (array) plus `row.merged` (bool). +- **Hide button on a merged row toggles `persons.filtered`**, not member-level flags. Splitting a member off later returns it unfiltered by design. +- **Merge can't span 3+ identities in one shot from the inline picker** — only pairwise. To merge a third controller into an existing person, use the People modal → that person → add member. (Or split + remerge.) +- **Webhook ingest is still untouched.** Both filtering and merging are display-time only. The DB never loses an event; unmerging/unfiltering always restores complete history. + +**Repo path note:** Jason was working from `D:\REMOTE CODING\unifi-access-dashboard` this session, not the `F:\CODING\` path recorded at the top of this file. Not changing the canonical path automatically — flag if this is a permanent move. + +### Repo path clarification (per Jason, 2026-05-28) + +The earlier note about working from `D:\REMOTE CODING\unifi-access-dashboard` vs the canonical `F:\CODING\` is **expected** — this repo is checked out on multiple machines with different folder structures. Don't treat divergent local paths as a red flag; the canonical reference is the Gitea repo and the deployed container, not any one machine's checkout location. diff --git a/.source-references/references-only/reference vault/memory/projects/unraid-deployment.md b/.source-references/references-only/reference vault/memory/projects/unraid-deployment.md new file mode 100644 index 0000000..dac8deb --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/unraid-deployment.md @@ -0,0 +1,86 @@ +--- +type: project +status: reference +tags: [infrastructure, docker, unraid, deployment] +updated: 2026-05-29 +--- + +# Preferred Deployment Workflow + +Reference: [[deployment-guide]] (saved to F:\CLAUDE\COWORK\COWORK\deployment-guide.md) + +## Pipeline summary + +``` +Code (Claude Code / Antigravity / VSCode) + → git push main to git.alwisp.com + → Gitea Actions triggers .gitea/workflows/docker-build.yml + → Runner builds & pushes to registry.alwisp.com/{owner}/{repo}:latest + → Unraid Docker GUI: add container manually +``` + +## Gitea Actions workflow pattern + +- Runner image: `catthehacker/ubuntu:act-latest` +- Registry: `registry.alwisp.com` +- Secrets: `REGISTRY_USER`, `REGISTRY_TOKEN` +- Tag pattern: `registry.alwisp.com/{owner}/{repo}:latest` +- Trigger: push to `main` branch only + +## Unraid container standards + +### Network +- Always **Custom: br0** (not bridge) +- Subnet: `10.2.0.0/24` +- Each app gets a fixed dedicated IP + +### Known fixed IPs +| App | IP | Notes | +|---|---|---| +| adminer | 10.2.0.2:7070 | bridge | +| alwisp_db | 10.2.0.7 | | +| alwisp_web | 10.2.0.8 | | +| breedr | 10.2.0.17 | | +| codedump | 10.2.0.34 | | +| cpas | 10.2.0.14 | | +| email-sigs | 10.2.0.10 | | +| fabdash | 10.2.0.13 | | +| Gitea | 10.2.0.15 | | +| gitea-mcp | 10.2.0.16 | | +| Gitea-Runner | 172.17.0.7 | bridge | +| inven | 10.2.0.25 | | +| invoiceninja-v5 | 10.2.0.2:8000, 10.2.0.2:8444 | bridge | +| MariaDB-Official | 10.2.0.2:3306 | bridge | +| matter-server | 10.2.0.2 | host network | +| memer | 10.2.0.30 | | +| mrp | 10.2.0.19 | | +| mrp-qrcode | 10.2.0.32 | | +| n8n | — | stopped | +| NEBULA | 10.2.0.5 | | +| NGINX | 10.2.0.3 | | +| nyaa | 10.2.0.21 | | +| obsidian | 10.2.0.2:3000, 10.2.0.2:3001 | bridge | +| OpenClaw | — | br0, IP not shown | +| plex | 10.2.0.2 | host network | +| postgresql16 | 10.2.0.2:5432 | bridge | +| QR.knit | 10.2.0.9 | | +| rackmapper | 10.2.0.23 | | +| Redis | 10.2.0.2:6379 | bridge | +| stepview | 10.2.0.33 | | +| syncthing | 10.2.0.2:8384, 10.2.0.2:21027 | bridge | +| ui-tracker | 10.2.0.29 | | +| UISP | 10.2.0.4 | | +| unifi-access-dashboard | 10.2.0.11 | | +| wfh | 10.2.0.18 | | + +### Volume convention +- Host: `/mnt/user/appdata/{app-name}/` +- Container: `/app/data`, `/data`, `/app/uploads`, `/app/static`, `/app/secrets` + +### Standard env vars +`PORT`, `NODE_ENV=production`, `ADMIN_USERNAME`/`ADMIN_USER`, `ADMIN_PASSWORD`/`ADMIN_PASS`, `DB_PATH`, `DATA_DIR`, `PUBLIC_URL`, `CRON_SCHEDULE`, `TZ=America/Chicago`, `STATIC_PATH` + +### Defaults +- Privileged: OFF +- Tailscale: OFF +- Console: Shell diff --git a/.source-references/references-only/reference vault/memory/projects/wfh.md b/.source-references/references-only/reference vault/memory/projects/wfh.md new file mode 100644 index 0000000..baa09cb --- /dev/null +++ b/.source-references/references-only/reference vault/memory/projects/wfh.md @@ -0,0 +1,76 @@ +--- +type: project +status: active +source: git.alwisp.com +repo: jason/wfh +repo_url: https://git.alwisp.com/jason/wfh +language: TypeScript +branch: master +tags: [repo, jason] +updated: 2026-05-29 +--- + +# wfh + +**Repository:** [jason/wfh](https://git.alwisp.com/jason/wfh) · branch `master` · TypeScript + +## Summary + +Work From Home - Progress Tracker + +## Current status + +Active. Synced from Gitea on 2026-05-29. + +## Documentation overview + +# WFH Daily Report App + +A sleek, modern, and dockerized web application for employees to track and submit their daily work-from-home reports. Features a stunning glassmorphic design and seamless integration with Google Workspace. + +## ✨ Features + +- **Premium UI**: Modern glassmorphism aesthetics with smooth animations and responsive design. +- **Google OAuth 2.0**: Secure authentication using your company's Google Workspace accounts. +- **Multi-Step Reporting**: + - **Morning**: Log planned tasks, time estimates, and initial notes. + - **Evening**: Review achievements, update statuses, and submit links to completed work. +- **Smart Admin Logic**: + - The first user to log in is automatically granted the **ADMIN** role. + - Exclusive **Admin Panel** to search and review all employee reports. +- **Google Drive Integration**: + - Automatically exports completed reports as Google Docs. + - Admins can designate a specific folder for all exports. +- **Single-Container Architecture**: Uses SQLite for persistent storage, making it ideal for "drop-in" deployments (e.g., Unraid, Synology). + +## 🚀 Quick Start + +### 1. Prerequisites +- [Google Cloud Console](https://console.cloud.google.com/) Project with: + - OAuth 2.0 Credentials (Web Application) + - Google Drive API enabled +- Docker installed on your host. + +### 2. Environment Setup +Copy `.env.example` to `.env` and provide your credentials: +```bash +cp .env.example .env +``` + +### 3. Run with Docker +```bash +# Build and run the container +docker build -t wfh-report . +docker run -p 3000:3000 \ + --env-file .env \ + -v $(pwd)/data:/app/data \ + wfh-report +``` + +## 🏡 Unraid Installation + +…(truncated — see repo) + +## Notes + +- Project file auto-created from repo documentation. diff --git a/.source-references/references-only/reference vault/memory/sessions/2026-05-27-cpas-authentication.md b/.source-references/references-only/reference vault/memory/sessions/2026-05-27-cpas-authentication.md new file mode 100644 index 0000000..dce9208 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/sessions/2026-05-27-cpas-authentication.md @@ -0,0 +1,54 @@ +--- +type: session +date: 2026-05-27 +project: cpas +tags: + - cpas + - authentication + - docker + - scrypt + - sessions + - mpm +--- + +# [[CPAS]] — Authentication, user management, and docs + +## Summary + +Added a login popup, env-bootstrapped admin account, and admin-managed user CRUD to the CPAS Violation Tracker. Replaced the long-standing `TODO [CRITICAL #1]` (no auth on any route). Updated in-app docs and the Unraid install guide. + +## What shipped + +- **Backend** (`auth.js`, `db/database.js`, `server.js`) + - scrypt password hashing (Node built-in `crypto`, no new deps) + - `users` and `sessions` tables (sessions = DB-backed, 7-day TTL, hex tokens) + - `bootstrapAdmin()` creates/syncs admin from `ADMIN_USERNAME`/`ADMIN_PASSWORD` on every startup → password owned by Docker env + - `requireAuth` / `requireAdmin` Express middleware + - Public: `/api/health`, `POST /api/auth/login`. Everything else guarded by `app.use('/api', auth.requireAuth)`. + - User mgmt: `GET/POST /api/users`, `PATCH /api/users/:id/password`, `DELETE /api/users/:id` (all admin-only). Audit log entries for login attempts and user changes. +- **Frontend** (`client/src/auth.js`, `LoginModal.jsx`, `UserManagementModal.jsx`, `App.jsx`) + - axios interceptors inject `Bearer` token from localStorage, auto-logout on 401 + - Auth gate in App: validates stored token via `/api/auth/me` on load, shows LoginModal if no session + - Nav: user badge, Logout, and admin-only **Users** button +- **Docker** — `ENV ADMIN_USERNAME=admin` and `ENV ADMIN_PASSWORD=changeme` (placeholder, must override) +- **Docs** — in-app admin guide (`ReadmeModal.jsx`) gained an "Authentication & User Accounts" section; auth moved into Roadmap → Shipped; `README_UNRAID_INSTALL.md` adds the two new env-var rows + login verify step + troubleshooting for forgotten admin password. + +## Key decisions + +- Used Node's built-in `crypto.scryptSync` to **avoid adding bcrypt** as a dependency. Storage format: `scrypt$$`. Constant-time compare via `crypto.timingSafeEqual`. +- DB-backed sessions instead of JWT or in-memory map → survives container restarts, single source of truth, easy admin revoke if needed. +- Admin password **re-syncs from env on every startup**. Trade-off: admin can't change their own password in UI (it would be reverted on restart), but rotating the env var rotates the live credential — clean operational story. +- Did **not** wrap `window.fetch`. All component API calls go through axios; the lone bare `fetch('/version.json')` hits a public static file. So axios interceptors are sufficient. +- PDF downloads use `axios.get(..., { responseType: 'blob' })`, not anchor links → interceptor still attaches the token, no special-case needed. + +## Loose ends / future work + +- No password-change UI for non-admin users yet (admins reset for them). +- No expired-session cleanup job (lazy prune only). +- Only admin/user roles. Supervisor-scoped or read-only roles still open. + +## Verification status + +- `node --check` passes on `auth.js`, `server.js`, `db/database.js`. +- `client && npm run build` succeeds. +- **Could not run server locally** — `better-sqlite3` fails to compile against local Node v24. Builds fine in the Docker `node:20-alpine` image; full verification requires building and running the container. diff --git a/.source-references/references-only/reference vault/memory/sessions/2026-05-27-gitea-repo-descriptions.md b/.source-references/references-only/reference vault/memory/sessions/2026-05-27-gitea-repo-descriptions.md new file mode 100644 index 0000000..6ee9bde --- /dev/null +++ b/.source-references/references-only/reference vault/memory/sessions/2026-05-27-gitea-repo-descriptions.md @@ -0,0 +1,34 @@ +--- +type: session +date: 2026-05-27 +tags: + - gitea + - git-alwisp + - repo-maintenance + - mpm +--- + +# Session: Gitea Repo Description Sweep — 2026-05-27 + +## What happened + +Used the git-personal:gitea skill to audit and update all `/jason` repos on git.alwisp.com that were missing descriptions. + +## Key outcomes + +- 47 total repos enumerated for `jason` user on git.alwisp.com +- 25 repos had no description at session start +- Read README.md and project-specific .md files (PROJECT.md, JARVIS.md, INSTALL.md, etc.) from each repo to derive accurate descriptions +- Successfully patched 23 repos with descriptions via Gitea API PATCH +- **stepview** clarified by Jason: self-hosted in-browser 3D STEP file viewer (OpenCascade WASM + three.js) +- **qrknit** clarified by Jason: commercial QR code generator and URL shortener — lives under `qrknit/qrknit` org (not `jason/`) +- **google-mcp** belongs to `mpm` org — Jason declined to update it + +## Repo ownership notes + +- `qrknit` is its own org: `qrknit/qrknit` on git.alwisp.com +- `google-mcp` belongs to `mpm` org on git.alwisp.com + +## Repos updated (previously blank) + +agents, alwisp, breedr, codedump, codexium-odoo, cpas, email, fabdash, family-planner, inven, jarvis, memer, mempalace, mrp, mrp-qrcode, nyaa-crawler, pos, rack-planner, stellar, stepview, storybid, totalmcp, ui-tracker, qrknit (under qrknit org) diff --git a/.source-references/references-only/reference vault/memory/sessions/2026-05-27-obsidian-memory-plugin-build.md b/.source-references/references-only/reference vault/memory/sessions/2026-05-27-obsidian-memory-plugin-build.md new file mode 100644 index 0000000..90a767f --- /dev/null +++ b/.source-references/references-only/reference vault/memory/sessions/2026-05-27-obsidian-memory-plugin-build.md @@ -0,0 +1,38 @@ +--- +type: session +tags: [obsidian, cowork, plugin, memory] +updated: 2026-05-27 +--- + +# Session: Built obsidian-memory-plugin Cowork Plugin + +**Date:** 2026-05-27 +**Topic:** Designed and built the [[obsidian-memory-plugin]] for Claude Cowork + +## What happened + +Jason wanted Claude to have persistent memory across Cowork sessions using his Obsidian vault (running Local REST API at 10.2.0.2:27124). We built a skill-only plugin — no MCP server — that calls the REST API directly via bash/curl. The plugin includes a lean SKILL.md and four reference files. It was packaged as obsidian-memory.plugin and installed. Vault was bootstrapped in the same session. + +## Decisions made + +- Skill-only plugin (no MCP): direct curl calls are simpler and sufficient for a personal plugin, and produce a single distributable file +- API key hardcoded in skill (personal plugin, not for sharing) +- SSL verification skipped with `-k` (self-signed Obsidian cert) +- Temp file pattern (`cat > /tmp/obs_entry.md`) used for all multi-line writes to avoid heredoc quoting issues + +## Artifacts produced + +- `obsidian-memory.plugin` — installed in Cowork +- `Projects/agents/README.md` — vault index (bootstrapped) +- `Projects/agents/memory/profile.md` — Jason's persistent profile (empty, to be filled) +- `Projects/agents/memory/inbox.md` — untriaged notes inbox +- `Projects/agents/memory/projects/obsidian-memory-plugin.md` — this project's state + +## Open threads + +- [ ] Fill in profile.md (role, preferences, tools stack) as facts come up in conversations +- [ ] Test memory recall in a fresh session — load README → profile → relevant project + +## Next step + +In the next substantive session, load memory silently at the start (README → profile) and start populating profile.md as Jason's role and preferences emerge. diff --git a/.source-references/references-only/reference vault/memory/sessions/2026-05-27-personal-gitea-plugin.md b/.source-references/references-only/reference vault/memory/sessions/2026-05-27-personal-gitea-plugin.md new file mode 100644 index 0000000..9009fd9 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/sessions/2026-05-27-personal-gitea-plugin.md @@ -0,0 +1,29 @@ +--- +type: session +date: 2026-05-27 +tags: [gitea, plugin, cowork] +--- + +# 2026-05-27 — Personal Gitea Plugin + +## What happened + +Built a personal Gitea plugin (`git-personal`) for git.alwisp.com, forked from the existing work plugin (`git-mpm` targeting git.mpm.to). Updated all server URLs, API key, and plugin metadata throughout 8 files. + +Then updated the plugin's file upload patterns to avoid a known base64 encoding problem. + +## Decisions made + +- Personal plugin lives separately from the work plugin — same skill structure, different credentials and base URL +- File create/update operations now use Python + temp files for base64 encoding instead of `echo -n | base64` (which caused silent corruption via line-wrapping and shell escaping) +- Reads always use the `/raw/` endpoint rather than decoding the base64 `content` field from `/contents/` +- JSON payloads are written to a temp file and passed via `--data-binary @file` to avoid shell escaping issues + +## Artifacts + +- `F:\CLAUDE\COWORK\COWORK\git-personal.plugin` — ready to install + +## Open threads / next steps + +- None identified + diff --git a/.source-references/references-only/reference vault/memory/sessions/2026-05-28-uad-filter-and-merge.md b/.source-references/references-only/reference vault/memory/sessions/2026-05-28-uad-filter-and-merge.md new file mode 100644 index 0000000..7b12932 --- /dev/null +++ b/.source-references/references-only/reference vault/memory/sessions/2026-05-28-uad-filter-and-merge.md @@ -0,0 +1,58 @@ +--- +type: session +project: unifi-access-dashboard +tags: + - unifi + - flask + - sqlite + - filtering + - identity-merging + - access + - attendance +updated: 2026-05-28 +--- + +# 2026-05-28 — [[UniFi-Access-Dashboard]]: tenant filtering + identity merging + +Same-day follow-up to the multi-controller ship. Two features added back-to-back, both purely additive at the DB layer. + +## What got built + +**Tenant filtering** — one-click Hide/Unhide on the attendance table so building tenants (and any non-staff badge holder) don't trip the LATE warning or clutter the daily view. Filtered actors are excluded from `/api/first-badge-status` by default; a "Show filtered" toggle re-includes them as dimmed rows tagged FILTERED. A 🚫 Filtered header button opens a modal listing all filtered actors for bulk unhide. + +**Identity merging** — same physical person on two controllers gets two UUIDs from UniFi, which produces split first-badge times (and false LATE warnings). The new `persons` + `person_members` tables let the user group N `(controller_id, actor_id)` rows under a single person with one editorial display name. The attendance query groups by `COALESCE(person_id, controller||'|'||actor)` so merged rows collapse to a single line; the Source column renders a chip per controller plus a MERGED pill. A People modal auto-suggests merges based on exact full-name matches across distinct controllers — one click per suggestion, never auto-applied. + +## Key decisions + +- **Schema shape**: chose `persons` + `person_members` tables (Option A) over a `merge_group` column on `user_cache` (Option B) or a self-referential `merged_into` (Option C). Reasoning: `user_cache` is a sync cache; `persons` is the editorial layer that can grow per-person fields later (notes, department, photo) without polluting the sync table. +- **Filtering semantics with merge**: `COALESCE(p.filtered, u.filtered, 0)` — person-level filter wins when merged, actor-level applies when not. Split-off members return unfiltered (person filter dies with the merge); simpler mental model than inheriting. +- **Webhook ingest untouched**: both features are display-time only. No DB row is ever lost. Unmerging/unfiltering instantly restores complete history. +- **Auto-suggestions are conservative**: only exact name matches across ≥2 distinct controllers, excluding "User xxxxx" placeholders. No fuzzy matching at suggestion time (the inline merge picker does fuzzy search for manual cases). + +## Files touched + +- `app.py` — added two migrations (`filtered` column on `user_cache`, `persons` + `person_members` tables), reworked `/api/first-badge-status`, added 11 new endpoints (users CRUD + persons CRUD + suggestions). +- `static/index.html` — new Filtered modal, new People modal with merge picker, Hide/Merge buttons in an Actions column, multi-chip Source rendering, MERGED pill, Show filtered toggle. +- `README.md` — new "Filtering tenants" and "Merging identities across controllers" sections, new troubleshooting rows, full endpoint table refresh. + +## Sharp edges + +- Inline merge picker is **pairwise only**. For 3+ controllers per person, merge two first then use People modal → Add member. +- Source field in API response: kept `row.source` (single string) for backwards compat; the new arrays are `row.sources` and `row.controller_ids`. Any consumer using the old field still works. +- `Local REST API` plugin on the vault rejects `PATCH ... Target-Type: heading` with `invalid-target` even for documented examples — the heading-addressed PATCH is broken on this server's plugin version. Used `POST` (append-to-EOF) instead. Worth investigating later but not blocking. + +## Repo path observation + +Working directory this session was `D:\REMOTE CODING\unifi-access-dashboard`, not the `F:\CODING\unifi-access-dashboard` path recorded as canonical in `[[unifi-access-dashboard]]`. Did not silently update the project file's path field — flag if it's a permanent move. + +## Pre-existing code review issues (still unaddressed) + +These were noted in earlier project memory and the filter+merge work didn't touch them: + +1. Webhook signature fails *open* when secret is empty (`app.py:252-254`) — intentional LAN-trust mode per Jason. +2. All `/api/*` endpoints unauthenticated — intentional per README. +3. `first <= cutoff_end` is string-lex compare on `HH:MM:SS` — works but brittle. +4. No index on `badge_events(date, controller_id)` — full scan per page load. Will degrade at scale. +5. `verify=False` for self-signed UniFi certs is undocumented inline. + +The new features inherit the same LAN-trust posture, so anyone with LAN access can also POST to `/api/persons/...` or `/api/users/...` and mutate filter/merge state. Consistent with existing design. diff --git a/.source-references/references-only/reference vault/memory/sessions/2026-05-28-unifi-dashboard-multi-controller.md b/.source-references/references-only/reference vault/memory/sessions/2026-05-28-unifi-dashboard-multi-controller.md new file mode 100644 index 0000000..0a282ee --- /dev/null +++ b/.source-references/references-only/reference vault/memory/sessions/2026-05-28-unifi-dashboard-multi-controller.md @@ -0,0 +1,37 @@ +--- +type: session +date: 2026-05-28 +tags: + - unifi-access-dashboard + - refactor + - multi-controller + - access + - mpm +--- + +# 2026-05-28 — UniFi Access Dashboard: multi-controller refactor + +## Context +Single-controller Flask app needed to support a client whose on-site server has LAN reach to multiple UniFi Access controllers. They want one dashboard showing badge events from all of them. + +## Decisions made +- Per-controller webhook URLs (`/api/unifi-access/`), legacy alias kept for back-compat. +- Auto-register webhooks from the UI when adding a controller (drops the manual Python snippet from the old README). +- **No admin auth, plaintext tokens in SQLite** — Jason explicitly chose LAN-only trust over the recommended Fernet + ADMIN_PASSWORD setup. Documented in [[unifi-access-dashboard]] so it doesn't get re-litigated. +- Skipped CSV export for now (recommended bundle but Jason declined). +- Auto-sync interval shortened from 6h to 1h late in the session. + +## Files changed +`app.py` (major rewrite), `static/index.html` (controllers modal + Source column + filter), `requirements.txt` (+pytz), `README.md` (UI-driven setup flow), `.env.example`, deleted `static/uad-landing.html`. + +## Folded-in fixes +- `datetime.utcnow()` → `datetime.now(timezone.utc)` +- Cutoff string-compare bug (now sanitized to `HH:MM`) +- Pinned `pytz` (was imported but undeclared) + +## Not committed +End of session: changes are on `main` working tree only. No commit or push. Run `docker compose up -d --build` to deploy. + +## Open items +- Existing webhook on Access side won't be cleaned up if user removes the seeded Default controller and re-adds via UI → duplicate events. Covered in project notes as a known gotchas. +- Cross-controller identity merge (same human across sites) is explicitly out of scope. diff --git a/.source-references/references-only/reference-obsidian-memory.plugin b/.source-references/references-only/reference-obsidian-memory.plugin new file mode 100644 index 0000000000000000000000000000000000000000..5fb9e1390c52007423a0bcd37d12392f67c84738 GIT binary patch literal 11385 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" +``` + +### Missing root control docs +- `STRUCTURE.md`, `spinup.md`, `README.md`, `.env.example` — if absent, note it and reconstruct from the conventions in this file and [[STRUCTURE]]. Do not invent secrets in `.env.example`; use placeholders only. +- `index.md` — rebuild as a link hub pointing at the Start Here docs, current daily note, active context, latest session log, and active projects. + +### Missing templates +Recreate from the canonical frontmatter (section 4). Each template is just frontmatter plus the section headings its note type uses. + +### Missing anchor notes +- `_agent/context/current-context.md` — create an empty context bundle (type `context-bundle`) scoped to the current task. +- today's daily note — create from `journal/templates/daily-note-template.md`. +- `operator-preferences.md` — only create if you have evidence to record; do not fabricate preferences. + +### After repair +Append a line to the daily note's **Agent Log** and write/refresh a session log in `_agent/sessions/` recording what was generated. + +--- + +## 3. How to Use the Memory System + +Once preflight passes, operate as follows. + +### Session start +1. Read this file (bootstrap), then [[CLAUDE]]. +2. Read today's daily note in `journal/daily/`. +3. Read the most recent log in `_agent/sessions/`. +4. Read active bundles in `_agent/context/`. +5. Scan `inbox/` for unprocessed material relevant to the task. +6. Review active projects in `projects/active/` and open loops. + +### During the session +- Put short-lived state in `_agent/memory/working/` (expires; safe to prune). +- Promote durable, reusable facts and patterns into `_agent/memory/semantic/`. +- Record notable events and outcomes in `_agent/memory/episodic/`. +- Keep task-scoped context in `_agent/context/` and refresh it as focus shifts. +- Capture raw, unprocessed input in `inbox/captures/`; log processing in `inbox/processing-log/`. +- Record meaningful choices as decision notes in `decisions/` (mirror by-date and by-project as needed). + +### Session end +1. Write or update a session log in `_agent/sessions/` (`YYYY-MM-DD-HHMM-slug.md`). +2. Record what changed, decisions made, and what remains open. +3. Update durable notes if the session produced lasting knowledge. +4. Add a concise entry to the daily note's **Agent Log**. +5. Leave the vault cleaner and more queryable than you found it. + +### Memory model (where things live) +- **Working** → `_agent/memory/working/` — transient, time-boxed. +- **Episodic** → `_agent/memory/episodic/` — what happened, when. +- **Semantic** → `_agent/memory/semantic/` — durable facts, patterns, preferences. +- **Context bundles** → `_agent/context/` — task-focused reading lists and state. + +### Safety rules (from [[CLAUDE]]) +- Do not fabricate facts, relationships, or prior decisions. +- Do not mass-restructure the vault unless explicitly asked. +- Do not delete notes unless deletion is explicitly requested and clearly safe. +- Do not store secrets or API keys inside the vault. +- Default to additive updates and explicit status changes. + +--- + +## 4. Canonical Frontmatter + +Every note carries this block. Fill what applies; leave the rest empty rather than guessing. + +```yaml +--- +type: # one of the note types in STRUCTURE.md +status: # active | draft | done | archived +created: # YYYY-MM-DD +updated: # YYYY-MM-DD +tags: [] +agent_written: false +source_notes: [] # plain relative paths as strings — NEVER [[wikilinks]] +--- +``` + +Agent-generated notes set `agent_written: true` and list their `source_notes`. This is the key signal that separates agent-managed content from human-authored content. + +> **No `[[wikilinks]]` in frontmatter.** YAML interprets `[[...]]` as nested lists, so wiki +> links in frontmatter break — they do not render as clickable links in Obsidian's reading +> view. Put every cross-reference in a **`## Related`** section in the note **body** as a +> bulleted list of `[[links]]`. Frontmatter holds scalar/string metadata only; `source_notes` +> values are plain relative paths, not links. (The older `related:` frontmatter field has +> been retired for this reason.) + +--- + +## 5. REST / API Readiness + +Future clients (Obsidian Local REST API, CoWork plugin) may operate without filesystem access. Keep the bootstrap contract portable: stable paths, parseable frontmatter, durable titles, and all state stored in notes rather than hidden conversation memory. Config for those clients lives in a local `.env` derived from `.env.example` — never committed with real values. + +--- + +_This file is the entry point. If you change folder conventions or required files, update both this manifest and [[STRUCTURE]] so they stay in sync._ + +## Related +- [[CLAUDE]] +- [[STRUCTURE]] +- [[index]] +- [[spinup]] diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..4bf7efc --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,50 @@ +# CLAUDE.md + +## Purpose +This vault is a shared memory substrate for human work, Claude Code sessions, and future agent clients that access the vault through the Obsidian Local REST API or a CoWork plugin integration. The vault must remain readable by humans, writable by agents, and structured enough that tools can reliably navigate, synthesize, and update knowledge over time. + +## Core Principles +- Treat the vault as the system of record for long-term memory, not as a scratchpad. +- Prefer Markdown, YAML frontmatter, wiki-links, and stable folder conventions over proprietary structures. +- Write notes so both humans and agents can understand them without hidden context. +- Preserve history instead of silently overwriting important decisions, summaries, or inferred preferences. +- Keep agent-managed content clearly separated from human-authored content when possible. +- Default to additive updates, explicit status changes, and traceable summaries. +- Optimize for portability so the same vault can work with Claude Code, CoWork, MCP-compatible tools, REST API clients, and future agents. + +## What This Agent Is +You are an agent operating against an Obsidian vault that functions as an AI second brain. Your role is to read context, synthesize across notes, create structured outputs, update memory carefully, and leave durable traces of work in the vault rather than keeping important state inside the conversation only. + +## Bootstrap (Start Here) +Before anything else in a new session, read [[BOOTSTRAP]] (`BOOTSTRAP.md`). It is the entry point to the memory system: it verifies that the required files and folders exist, regenerates anything missing using the canonical conventions, and restates how to operate the vault. Only proceed to the Session Protocol below once the bootstrap preflight passes. Never overwrite existing files during bootstrap — generate only what is missing. + +## Session Protocol +At the start of each session: +0. Run the bootstrap preflight in [[BOOTSTRAP]] and repair any missing files/folders. +1. Read today’s daily note in `journal/daily/` if present. +2. Read the most recent relevant notes in `_agent/sessions/`. +3. Read active context files in `_agent/context/`. +4. Check `inbox/` for unprocessed material related to the task. +5. Review active project notes and open loops before taking action. + +At the end of each session: +1. Write or update a session log in `_agent/sessions/`. +2. Record what changed, what decisions were made, and what remains open. +3. Update related notes if the session produced durable knowledge. +4. Add a concise agent log block to the daily note when appropriate. +5. Leave the vault in a cleaner, more queryable state than it was at the start. + +## Memory Model +- Working memory: `_agent/memory/working/` +- Episodic memory: `_agent/memory/episodic/` +- Semantic memory: `_agent/memory/semantic/` +- Task-focused context bundles: `_agent/context/` + +## REST/API Readiness +Assume future clients may interact through the Obsidian Local REST API instead of direct filesystem access. Keep paths predictable, frontmatter parseable, titles stable, and state stored in notes rather than hidden memory. + +## Safety +- Do not fabricate facts, relationships, or prior decisions. +- Do not mass-restructure the vault unless explicitly asked. +- Do not delete notes unless deletion is explicitly requested and clearly safe. +- Do not store secrets or API keys inside the vault. diff --git a/README.md b/README.md index e69de29..41cd235 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,20 @@ +# Starter Memory Vault + +This is a review scaffold for an Obsidian-based memory vault designed for Claude Code, future CoWork plugin integration, and Obsidian Local REST API access. + +## Included +- Root control docs: `CLAUDE.md`, `STRUCTURE.md`, `BOOTSTRAP.md`, `spinup.md` +- Core knowledge folders +- Agent memory and session folders +- Starter templates +- Starter seed notes +- Index pages for navigation +- `.env.example` for future local integration config + +## Review focus +- Folder shape +- Frontmatter standards +- Note taxonomy +- Session flow +- Agent memory layout +- CoWork/API readiness diff --git a/STRUCTURE.md b/STRUCTURE.md new file mode 100644 index 0000000..da66d2a --- /dev/null +++ b/STRUCTURE.md @@ -0,0 +1,66 @@ +# STRUCTURE.md + +## Purpose +This document defines the vault layout, note taxonomy, naming conventions, and frontmatter templates for a memory storage vault designed for Claude Code today and future CoWork plugin access through the Obsidian Local REST API. + +## Recommended Vault Layout + +```text +vault/ +├── CLAUDE.md +├── STRUCTURE.md +├── BOOTSTRAP.md +├── spinup.md +├── index.md +├── README.md +├── inbox/ +├── journal/ +├── projects/ +├── areas/ +├── resources/ +├── decisions/ +├── reviews/ +├── _agent/ +└── archive/ +``` + +## Note Types +- daily-note +- weekly-note +- monthly-note +- project +- project-update +- area +- concept +- reference +- person +- meeting +- decision +- review +- session-log +- working-memory +- episodic-memory +- semantic-memory +- context-bundle +- skill +- draft +- inbox-item + +## Core Frontmatter +```yaml +--- +type: +status: +created: +updated: +tags: [] +agent_written: false +source_notes: [] # plain relative paths as strings — NEVER [[wikilinks]] +--- +``` + +> **No `[[wikilinks]]` in frontmatter.** YAML parses `[[...]]` as nested lists, so wiki +> links placed in frontmatter (e.g. an old `related:` field) silently break and do not +> render as clickable links. All cross-references go in a **`## Related`** section in the +> note **body**, as a bulleted list of `[[links]]`. Keep frontmatter to scalar/string +> metadata only. `source_notes`, when used, holds plain relative path strings, not links. diff --git a/_agent/context/current-context.md b/_agent/context/current-context.md new file mode 100644 index 0000000..1df458f --- /dev/null +++ b/_agent/context/current-context.md @@ -0,0 +1,45 @@ +--- +type: context-bundle +status: active +created: 2026-06-01 +updated: 2026-06-01 +tags: [agent, context] +agent_written: true +source_notes: [] +scope: vault-foundation +refresh_strategy: on-demand +--- + +# Current Context + +## Scope +Initial scaffold review for a Claude Code + Obsidian memory vault. + +## Active Priorities +- Review scaffold folders. +- Review templates. +- Review root docs. +- Plan REST API and CoWork plugin alignment. + +## Relevant Entities +- [[projects/active/vault-foundation]] +- [[resources/references/obsidian-local-rest-api]] +- [[resources/people/jason-stedwell]] + +## Key Decisions +- Separate durable knowledge from operational agent state. +- Preserve portability across direct filesystem and API-driven clients. + +## Open Questions +- Which note types should the plugin create directly? +- Should decisions live by project only, or by date and project? +- What should the session end hook write automatically? + +## Source Notes +- [[journal/daily/2026-06-01]] +- [[projects/active/vault-foundation]] + +## Related +- [[projects/active/vault-foundation]] +- [[journal/daily/2026-06-01]] +- [[_agent/sessions/2026-06-01-2200-initial-vault-scaffold]] diff --git a/_agent/heartbeat/README.md b/_agent/heartbeat/README.md new file mode 100644 index 0000000..35f1107 --- /dev/null +++ b/_agent/heartbeat/README.md @@ -0,0 +1,3 @@ +# Heartbeat + +Use this folder for periodic state snapshots, compression summaries, and maintenance reports. diff --git a/_agent/memory/episodic/README.md b/_agent/memory/episodic/README.md new file mode 100644 index 0000000..48a3677 --- /dev/null +++ b/_agent/memory/episodic/README.md @@ -0,0 +1,5 @@ +# episodic/ + +Episodic memory: notable events and outcomes, what happened and when. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/_agent/memory/semantic/operator-preferences.md b/_agent/memory/semantic/operator-preferences.md new file mode 100644 index 0000000..1e079d4 --- /dev/null +++ b/_agent/memory/semantic/operator-preferences.md @@ -0,0 +1,34 @@ +--- +type: semantic-memory +status: active +created: 2026-06-01 +updated: 2026-06-02 +tags: [agent, semantic-memory, preferences] +agent_written: true +source_notes: [] +confidence: medium +last_reviewed: 2026-06-02 +--- + +# Operator Preferences + +## Operator +The **primary operator** of this vault is [[resources/people/bryan-gilliom]] (Bryan Gilliom, CEO of Message Point Media). Unless stated otherwise, "the operator" below refers to Bryan. [[resources/people/jason-stedwell]] is the vault's architect/creator and a possible future collaborator; preferences attributed to the vault's design originate with Jason and should not be assumed to be Bryan's until observed. + +## Fact / Pattern +The vault is built around structured systems, clear roadmaps, durable documentation, and implementation-ready scaffolds. Bryan's own working preferences are not yet established and should be captured from real interactions rather than assumed. + +## Evidence +The vault's design and request history (root documentation, structural guidance, setup walkthroughs, plugin-oriented direction) reflect Jason's design intent as architect. No direct evidence of Bryan's preferences has been recorded yet. + +## Recommendation or Implication +Default to explicit files, repeatable workflows, and low-ambiguity structure when extending this vault. As Bryan uses the system, record observed preferences here with evidence and raise confidence accordingly — do not fabricate. + +## Review Notes +Reconfirm and attribute preferences to Bryan once direct interactions provide evidence; revisit at the start of the plugin development workflow. + +## Related +- [[CLAUDE]] +- [[resources/people/bryan-gilliom]] +- [[resources/people/jason-stedwell]] +- [[projects/active/vault-foundation]] diff --git a/_agent/memory/working/active-setup.md b/_agent/memory/working/active-setup.md new file mode 100644 index 0000000..5d8c39d --- /dev/null +++ b/_agent/memory/working/active-setup.md @@ -0,0 +1,30 @@ +--- +type: working-memory +status: active +created: 2026-06-01T22:00 +updated: 2026-06-01T22:00 +tags: [agent, working-memory] +agent_written: true +source_notes: [] +expires_after: 48h +--- + +# Working Context + +## Active Focus +Starter scaffold review and refinement. + +## Recent Decisions +- Include root navigation notes. +- Include config example for future REST/API use. + +## Open Threads +- Add hooks, policies, and plugin CRUD docs. + +## Relevant Links +- [[index]] +- [[README]] + +## Related +- [[_agent/context/current-context]] +- [[projects/active/vault-foundation]] diff --git a/_agent/outputs/briefs/README.md b/_agent/outputs/briefs/README.md new file mode 100644 index 0000000..f5f9c1b --- /dev/null +++ b/_agent/outputs/briefs/README.md @@ -0,0 +1,5 @@ +# briefs/ + +Agent-generated briefs. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/_agent/outputs/drafts/README.md b/_agent/outputs/drafts/README.md new file mode 100644 index 0000000..0621acc --- /dev/null +++ b/_agent/outputs/drafts/README.md @@ -0,0 +1,5 @@ +# drafts/ + +Agent-generated drafts. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/_agent/outputs/summaries/README.md b/_agent/outputs/summaries/README.md new file mode 100644 index 0000000..255a03a --- /dev/null +++ b/_agent/outputs/summaries/README.md @@ -0,0 +1,5 @@ +# summaries/ + +Agent-generated summaries. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/_agent/outputs/synthesis/README.md b/_agent/outputs/synthesis/README.md new file mode 100644 index 0000000..2130dec --- /dev/null +++ b/_agent/outputs/synthesis/README.md @@ -0,0 +1,5 @@ +# synthesis/ + +Agent-generated synthesis across notes. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/_agent/sessions/2026-06-01-2200-initial-vault-scaffold.md b/_agent/sessions/2026-06-01-2200-initial-vault-scaffold.md new file mode 100644 index 0000000..348d50d --- /dev/null +++ b/_agent/sessions/2026-06-01-2200-initial-vault-scaffold.md @@ -0,0 +1,53 @@ +--- +type: session-log +status: complete +created: 2026-06-01T22:00 +updated: 2026-06-01T22:00 +tags: [agent, session, scaffold] +agent_written: true +source_notes: [] +session_date: 2026-06-01 +client: claude-code +--- + +# Session Log + +## Goal +Create a reviewable starter scaffold for a memory-oriented Obsidian vault. + +## Notes Read +- [[CLAUDE]] +- [[STRUCTURE]] +- [[BOOTSTRAP]] +- [[spinup]] + +## Actions Taken +- Created the core folder tree. +- Added root operating documents. +- Added templates for high-value note types. +- Seeded example operational notes. +- Added API config example and review index. + +## Decisions Made +- Include `_agent/` as a first-class operational layer. +- Add a root `index.md` and `README.md` for review and navigation. +- Include `.env.example` but not actual config. + +## Outputs Created +- Starter vault scaffold +- Root docs +- Templates +- Seed notes + +## Open Threads +- Add plugin integration spec. +- Add startup/shutdown hooks. +- Add archive policy and sync policy notes. + +## Suggested Next Step +Review the scaffold and then generate a plugin spec plus note CRUD contract. + +## Related +- [[projects/active/vault-foundation]] +- [[_agent/context/current-context]] +- [[journal/daily/2026-06-01]] diff --git a/_agent/sessions/2026-06-02-1618-goldbrain-plugin-build.md b/_agent/sessions/2026-06-02-1618-goldbrain-plugin-build.md new file mode 100644 index 0000000..1fca707 --- /dev/null +++ b/_agent/sessions/2026-06-02-1618-goldbrain-plugin-build.md @@ -0,0 +1,58 @@ +--- +type: session-log +status: complete +created: 2026-06-02T16:18 +updated: 2026-06-02T16:18 +tags: [agent, session, plugin, rest-api, goldbrain] +agent_written: true +source_notes: ["resources/references/obsidian-local-rest-api.md", "references-only/reference-obsidian-memory.plugin"] +session_date: 2026-06-02 +client: cowork +--- + +# Session Log + +## Goal +Prep the goldbrain vault from the reference materials, stand up and verify the Obsidian Local REST API, and build the `goldbrain-memory` CoWork plugin ready to hand off to Bryan. + +## Notes Read +- [[BOOTSTRAP]], [[STRUCTURE]], [[CLAUDE]], [[spinup]] +- [[_agent/memory/semantic/operator-preferences]], [[resources/people/bryan-gilliom]] +- [[resources/references/obsidian-local-rest-api]] + +## Actions Taken +Reviewed the references-only materials (reference vault + the existing `obsidian-memory` plugin + REST API docs). Found the vault scaffold was structurally complete but plugin/REST-readiness was thin, so filled the stub API reference with a full command reference + memory routing map and refreshed `.env.example` for goldbrain. + +Diagnosed a `502` from the reverse proxy: the Obsidian Local REST API plugin was bound to `127.0.0.1`. Changed binding to `0.0.0.0` and added the proxy hostname to the cert SAN; API came up clean (v4.1.2, valid TLS). Verified a full write → read → list → delete round-trip. + +Confirmed the scaffold copy into the live vault, then created the 24 empty subfolders that file-copy had dropped (placeholder READMEs) so the full required tree resolves over the API. Marked spin-up steps complete. + +Built the `goldbrain-memory` plugin (skill + 4 reference files) adapted to: operator = Bryan, base URL `goldbrainapi.mpm.to`, vault-root paths, goldbrain's PARA + `_agent/` layout, canonical frontmatter, HHMM session logs. Live-tested every documented operation. + +Fixed two bugs found during testing: (1) v4.1.2 PATCH requires the **full `::`-delimited heading path** (bare subheading name returns `invalid-target`); (2) `[[wikilinks]]` in YAML frontmatter break in Obsidian's reading view — migrated all 23 affected notes to move links into a body `## Related` section, retired the `related:` frontmatter field, and codified the rule in STRUCTURE.md / BOOTSTRAP.md and the plugin docs. + +## Decisions Made +- Vault addressed at root (no `Projects/agents/` prefix) — goldbrain is a dedicated vault. +- API base URL `https://goldbrainapi.mpm.to`; no `-k` needed (valid cert behind reverse proxy → `192.168.86.15:27124`). +- API key hardcoded in the plugin only, never written into the vault (per the vault's own safety rule). +- Rule established: no `[[wikilinks]]` in frontmatter; all cross-references live in a body `## Related` section. `source_notes` holds plain relative path strings. +- PATCH heading targets must use the full `H1::H2` path. + +## Outputs Created +- `goldbrain-memory.plugin` — installable CoWork plugin (delivered to the goldbrain root folder) +- Full REST command reference + routing map in [[resources/references/obsidian-local-rest-api]] +- 24 folder-placeholder READMEs; 23 notes + templates migrated for the frontmatter-link fix + +## Open Threads +- [ ] Validate Claude Code direct filesystem access to the vault host (spin-up step 6). +- [ ] Capture Bryan's real preferences in [[_agent/memory/semantic/operator-preferences]] from actual use — do not fabricate. +- [ ] Begin the daily/session/review operating rhythm (spin-up step 8). + +## Suggested Next Step +Hand off `goldbrain-memory.plugin` to Bryan, install it, and run one live session to confirm the skill triggers and that load/write land correctly through the plugin. + +## Related +- [[projects/active/vault-foundation]] +- [[resources/references/obsidian-local-rest-api]] +- [[resources/people/bryan-gilliom]] +- [[BOOTSTRAP]] diff --git a/_agent/skills/active/README.md b/_agent/skills/active/README.md new file mode 100644 index 0000000..7fb4ed6 --- /dev/null +++ b/_agent/skills/active/README.md @@ -0,0 +1,3 @@ +# Active Skills + +Store reusable agent skills here with clear triggers, versioning, and expected outputs. diff --git a/_agent/skills/archived/README.md b/_agent/skills/archived/README.md new file mode 100644 index 0000000..ce26465 --- /dev/null +++ b/_agent/skills/archived/README.md @@ -0,0 +1,5 @@ +# archived/ + +Retired agent skills. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/_agent/templates/context-bundle-template.md b/_agent/templates/context-bundle-template.md new file mode 100644 index 0000000..0d64b5b --- /dev/null +++ b/_agent/templates/context-bundle-template.md @@ -0,0 +1,27 @@ +--- +type: context-bundle +status: active +created: {{date:YYYY-MM-DD}} +updated: {{date:YYYY-MM-DD}} +tags: [agent, context] +agent_written: true +source_notes: [] +scope: +refresh_strategy: on-demand +--- + +# Context Bundle Title + +## Scope + +## Active Priorities + +## Relevant Entities + +## Key Decisions + +## Open Questions + +## Source Notes + +## Related diff --git a/_agent/templates/semantic-memory-template.md b/_agent/templates/semantic-memory-template.md new file mode 100644 index 0000000..45f6988 --- /dev/null +++ b/_agent/templates/semantic-memory-template.md @@ -0,0 +1,23 @@ +--- +type: semantic-memory +status: active +created: {{date:YYYY-MM-DD}} +updated: {{date:YYYY-MM-DD}} +tags: [agent, semantic-memory] +agent_written: true +source_notes: [] +confidence: high +last_reviewed: {{date:YYYY-MM-DD}} +--- + +# Semantic Memory Title + +## Fact / Pattern + +## Evidence + +## Recommendation or Implication + +## Review Notes + +## Related diff --git a/_agent/templates/session-log-template.md b/_agent/templates/session-log-template.md new file mode 100644 index 0000000..05e0982 --- /dev/null +++ b/_agent/templates/session-log-template.md @@ -0,0 +1,29 @@ +--- +type: session-log +status: complete +created: {{date:YYYY-MM-DDTHH:mm}} +updated: {{date:YYYY-MM-DDTHH:mm}} +tags: [agent, session] +agent_written: true +source_notes: [] +session_date: {{date:YYYY-MM-DD}} +client: claude-code +--- + +# Session Log + +## Goal + +## Notes Read + +## Actions Taken + +## Decisions Made + +## Outputs Created + +## Open Threads + +## Suggested Next Step + +## Related diff --git a/_agent/templates/working-memory-template.md b/_agent/templates/working-memory-template.md new file mode 100644 index 0000000..ca0dc65 --- /dev/null +++ b/_agent/templates/working-memory-template.md @@ -0,0 +1,22 @@ +--- +type: working-memory +status: active +created: {{date:YYYY-MM-DDTHH:mm}} +updated: {{date:YYYY-MM-DDTHH:mm}} +tags: [agent, working-memory] +agent_written: true +source_notes: [] +expires_after: 48h +--- + +# Working Context + +## Active Focus + +## Recent Decisions + +## Open Threads + +## Relevant Links + +## Related diff --git a/archive/README.md b/archive/README.md new file mode 100644 index 0000000..a65444b --- /dev/null +++ b/archive/README.md @@ -0,0 +1,3 @@ +# Archive + +Move completed or inactive notes here instead of deleting them when they may still be useful later. diff --git a/archive/imports/README.md b/archive/imports/README.md new file mode 100644 index 0000000..1c74638 --- /dev/null +++ b/archive/imports/README.md @@ -0,0 +1,5 @@ +# imports/ + +Archived imported material. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/archive/notes/README.md b/archive/notes/README.md new file mode 100644 index 0000000..892e90f --- /dev/null +++ b/archive/notes/README.md @@ -0,0 +1,5 @@ +# notes/ + +Archived standalone notes. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/archive/projects/README.md b/archive/projects/README.md new file mode 100644 index 0000000..ec76f2c --- /dev/null +++ b/archive/projects/README.md @@ -0,0 +1,5 @@ +# projects/ + +Archived project material. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/areas/business/business-ops.md b/areas/business/business-ops.md new file mode 100644 index 0000000..e56033d --- /dev/null +++ b/areas/business/business-ops.md @@ -0,0 +1,22 @@ +--- +type: area +status: active +created: 2026-06-01 +updated: 2026-06-01 +tags: [area, business] +agent_written: false +source_notes: [] +--- + +# Business Ops + +## Scope +Operational business responsibilities that persist beyond any single project. + +## Active Concerns +- Documentation systems +- Client operations +- Tooling standardization + +## Related +- [[projects/active/vault-foundation]] diff --git a/areas/learning/learning-backlog.md b/areas/learning/learning-backlog.md new file mode 100644 index 0000000..4f50dfc --- /dev/null +++ b/areas/learning/learning-backlog.md @@ -0,0 +1,22 @@ +--- +type: area +status: active +created: 2026-06-01 +updated: 2026-06-01 +tags: [area, learning] +agent_written: false +source_notes: [] +--- + +# Learning Backlog + +## Scope +Topics worth exploring and formalizing into durable notes. + +## Current Topics +- Obsidian Local REST API details +- CoWork plugin design patterns +- Session compression into semantic memory + +## Related +- [[resources/references/obsidian-local-rest-api]] diff --git a/areas/personal/README.md b/areas/personal/README.md new file mode 100644 index 0000000..298f8fb --- /dev/null +++ b/areas/personal/README.md @@ -0,0 +1,5 @@ +# personal/ + +Ongoing personal responsibilities and notes. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/areas/systems/systems-architecture.md b/areas/systems/systems-architecture.md new file mode 100644 index 0000000..02e795a --- /dev/null +++ b/areas/systems/systems-architecture.md @@ -0,0 +1,23 @@ +--- +type: area +status: active +created: 2026-06-01 +updated: 2026-06-01 +tags: [area, systems] +agent_written: false +source_notes: [] +--- + +# Systems Architecture + +## Scope +System-level design decisions, infrastructure patterns, and integration planning. + +## Active Concerns +- Vault architecture +- API integration patterns +- Plugin interoperability + +## Related +- [[projects/active/vault-foundation]] +- [[resources/references/obsidian-local-rest-api]] diff --git a/decisions/by-date/README.md b/decisions/by-date/README.md new file mode 100644 index 0000000..02ed320 --- /dev/null +++ b/decisions/by-date/README.md @@ -0,0 +1,5 @@ +# by-date/ + +Decision records indexed chronologically. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/decisions/by-project/README.md b/decisions/by-project/README.md new file mode 100644 index 0000000..8ea81c7 --- /dev/null +++ b/decisions/by-project/README.md @@ -0,0 +1,5 @@ +# by-project/ + +Decision records mirrored by project. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/decisions/decision-template.md b/decisions/decision-template.md new file mode 100644 index 0000000..88b014e --- /dev/null +++ b/decisions/decision-template.md @@ -0,0 +1,25 @@ +--- +type: decision +status: complete +created: {{date:YYYY-MM-DD}} +updated: {{date:YYYY-MM-DD}} +tags: [decision] +agent_written: true +source_notes: [] +decision_date: {{date:YYYY-MM-DD}} +impact: medium +--- + +# Decision Title + +## Context + +## Decision + +## Rationale + +## Consequences + +## Follow-Up + +## Related diff --git a/inbox/captures/README.md b/inbox/captures/README.md new file mode 100644 index 0000000..ac21201 --- /dev/null +++ b/inbox/captures/README.md @@ -0,0 +1,3 @@ +# Inbox Captures + +Drop raw captures here before they are processed into canonical notes. diff --git a/inbox/imports/README.md b/inbox/imports/README.md new file mode 100644 index 0000000..7cf4488 --- /dev/null +++ b/inbox/imports/README.md @@ -0,0 +1,5 @@ +# imports/ + +Raw imported material awaiting processing. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/inbox/processing-log/README.md b/inbox/processing-log/README.md new file mode 100644 index 0000000..30d92eb --- /dev/null +++ b/inbox/processing-log/README.md @@ -0,0 +1,5 @@ +# processing-log/ + +Logs of how inbox items were triaged and where they went. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/index.md b/index.md new file mode 100644 index 0000000..dd372c7 --- /dev/null +++ b/index.md @@ -0,0 +1,28 @@ +# Vault Index + +## Start Here +- [[README]] +- [[CLAUDE]] +- [[STRUCTURE]] +- [[BOOTSTRAP]] +- [[spinup]] + +## Operational Notes +- [[journal/daily/2026-06-01]] +- [[_agent/context/current-context]] +- [[_agent/sessions/2026-06-01-2200-initial-vault-scaffold]] +- [[projects/active/vault-foundation]] + +## Core Areas +- [[areas/business/business-ops]] +- [[areas/systems/systems-architecture]] +- [[areas/learning/learning-backlog]] + +## Reference Notes +- [[resources/concepts/agent-memory-model]] +- [[resources/references/obsidian-local-rest-api]] +- [[resources/people/bryan-gilliom]] +- [[resources/people/jason-stedwell]] + +## Reviews +- [[reviews/weekly/2026-W23]] diff --git a/journal/daily/2026-06-01.md b/journal/daily/2026-06-01.md new file mode 100644 index 0000000..a5b7857 --- /dev/null +++ b/journal/daily/2026-06-01.md @@ -0,0 +1,37 @@ +--- +type: daily-note +status: active +created: 2026-06-01 +updated: 2026-06-01 +tags: [daily, journal] +agent_written: false +source_notes: [] +--- + +# 2026-06-01 + +## Top Priorities +- Review and refine starter memory vault scaffold. +- Finalize note taxonomy and folder layout. +- Prepare for future Obsidian REST API and CoWork plugin work. + +## Schedule / Commitments +- Initial vault design and scaffold review. + +## Open Loops +- Decide whether to keep `areas/` broad or business-specific. +- Decide which templates should be exposed in the plugin UI first. +- Decide how session compression should roll into semantic memory. + +## Notes +This vault is being initialized as a human-plus-agent memory system. + +## Context for AI +Prioritize stable structure, machine-readable metadata, and low-friction future API access. + +## Agent Log +- Initial scaffold generated for review. + +## Related +- [[projects/active/vault-foundation]] +- [[_agent/context/current-context]] diff --git a/journal/daily/2026-06-02.md b/journal/daily/2026-06-02.md new file mode 100644 index 0000000..a3b030e --- /dev/null +++ b/journal/daily/2026-06-02.md @@ -0,0 +1,27 @@ +--- +type: daily-note +status: active +created: 2026-06-02 +updated: 2026-06-02 +tags: [daily, journal] +agent_written: false +source_notes: [] +--- + +# 2026-06-02 + +## Top Priorities + +## Schedule / Commitments + +## Open Loops + +## Notes + +## Context for AI + +## Agent Log + +- 16:18 — Built and verified the goldbrain-memory plugin; see [[_agent/sessions/2026-06-02-1618-goldbrain-plugin-build]]. + +## Related \ No newline at end of file diff --git a/journal/monthly/README.md b/journal/monthly/README.md new file mode 100644 index 0000000..2f4a8a6 --- /dev/null +++ b/journal/monthly/README.md @@ -0,0 +1,5 @@ +# monthly/ + +Monthly journal notes. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/journal/templates/daily-note-template.md b/journal/templates/daily-note-template.md new file mode 100644 index 0000000..5bbe593 --- /dev/null +++ b/journal/templates/daily-note-template.md @@ -0,0 +1,25 @@ +--- +type: daily-note +status: active +created: {{date:YYYY-MM-DD}} +updated: {{date:YYYY-MM-DD}} +tags: [daily, journal] +agent_written: false +source_notes: [] +--- + +# {{date:YYYY-MM-DD}} + +## Top Priorities + +## Schedule / Commitments + +## Open Loops + +## Notes + +## Context for AI + +## Agent Log + +## Related diff --git a/journal/templates/weekly-review-template.md b/journal/templates/weekly-review-template.md new file mode 100644 index 0000000..dbfd00a --- /dev/null +++ b/journal/templates/weekly-review-template.md @@ -0,0 +1,26 @@ +--- +type: review +status: active +created: {{date:gggg-[W]WW}} +updated: {{date:gggg-[W]WW}} +tags: [review, weekly] +agent_written: true +source_notes: [] +period: weekly +--- + +# Weekly Review + +## Completed Work + +## Open Loops + +## Stale Projects + +## Decisions + +## Priorities Next Week + +## Agent Notes + +## Related diff --git a/journal/weekly/README.md b/journal/weekly/README.md new file mode 100644 index 0000000..f2e7a43 --- /dev/null +++ b/journal/weekly/README.md @@ -0,0 +1,5 @@ +# weekly/ + +Weekly journal notes. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/projects/active/vault-foundation.md b/projects/active/vault-foundation.md new file mode 100644 index 0000000..b6fb472 --- /dev/null +++ b/projects/active/vault-foundation.md @@ -0,0 +1,54 @@ +--- +type: project +status: active +created: 2026-06-01 +updated: 2026-06-01 +tags: [project, vault] +agent_written: false +source_notes: [] +owner: Jason Stedwell +review_cycle: weekly +--- + +# Vault Foundation + +## Purpose +Build an Obsidian memory vault scaffold that supports Claude Code now and future CoWork plugin access later. + +## Status +Scaffold created and ready for review. + +## Goals +- Create clean root docs. +- Establish predictable folder structure. +- Define frontmatter and note taxonomy. +- Seed initial notes and templates. +- Prepare for REST API integration. + +## Current Context +This project is the setup layer for the broader memory vault system. + +## Open Loops +- Finalize plugin-facing CRUD conventions. +- Decide how reviews should promote working memory into semantic memory. +- Determine whether to add dashboards or MOC notes in v1. + +## Key Decisions +- Separate `_agent/` from human-facing knowledge folders. +- Use frontmatter-based note typing. +- Keep secrets outside the vault. + +## Related Notes +- [[index]] +- [[BOOTSTRAP]] +- [[spinup]] +- [[resources/concepts/agent-memory-model]] + +## Session History +- [[_agent/sessions/2026-06-01-2200-initial-vault-scaffold]] + +## Related +- [[CLAUDE]] +- [[STRUCTURE]] +- [[_agent/context/current-context]] +- [[journal/daily/2026-06-01]] diff --git a/projects/archived/README.md b/projects/archived/README.md new file mode 100644 index 0000000..d36641f --- /dev/null +++ b/projects/archived/README.md @@ -0,0 +1,5 @@ +# archived/ + +Completed or abandoned projects. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/projects/incubating/README.md b/projects/incubating/README.md new file mode 100644 index 0000000..09daa95 --- /dev/null +++ b/projects/incubating/README.md @@ -0,0 +1,5 @@ +# incubating/ + +Early-stage project ideas not yet active. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/projects/on-hold/README.md b/projects/on-hold/README.md new file mode 100644 index 0000000..ae8e470 --- /dev/null +++ b/projects/on-hold/README.md @@ -0,0 +1,5 @@ +# on-hold/ + +Paused projects, kept for later resumption. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/projects/project-template.md b/projects/project-template.md new file mode 100644 index 0000000..0b08cc3 --- /dev/null +++ b/projects/project-template.md @@ -0,0 +1,31 @@ +--- +type: project +status: active +created: {{date:YYYY-MM-DD}} +updated: {{date:YYYY-MM-DD}} +tags: [project] +agent_written: false +source_notes: [] +owner: +review_cycle: weekly +--- + +# Project Name + +## Purpose + +## Status + +## Goals + +## Current Context + +## Open Loops + +## Key Decisions + +## Related Notes + +## Session History + +## Related diff --git a/resources/concepts/agent-memory-model.md b/resources/concepts/agent-memory-model.md new file mode 100644 index 0000000..db68640 --- /dev/null +++ b/resources/concepts/agent-memory-model.md @@ -0,0 +1,32 @@ +--- +type: concept +status: reference +created: 2026-06-01 +updated: 2026-06-01 +tags: [concept, memory, agent] +agent_written: false +source_notes: [] +--- + +# Agent Memory Model + +## Summary +This vault uses a layered memory design with working memory, episodic memory, semantic memory, and task-focused context bundles. + +## Key Details +- Working memory supports active session execution. +- Episodic memory preserves what happened. +- Semantic memory stores stable patterns and durable knowledge. +- Context bundles provide compact, high-value retrieval targets. + +## Why It Matters +This separation reduces clutter and makes future API-driven retrieval more efficient. + +## Related Concepts +- [[resources/references/obsidian-local-rest-api]] +- [[projects/active/vault-foundation]] + +## Related +- [[CLAUDE]] +- [[_agent/context/current-context]] +- [[_agent/memory/semantic/operator-preferences]] diff --git a/resources/meetings/README.md b/resources/meetings/README.md new file mode 100644 index 0000000..b8767e5 --- /dev/null +++ b/resources/meetings/README.md @@ -0,0 +1,5 @@ +# meetings/ + +Meeting notes and records. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/resources/people/bryan-gilliom.md b/resources/people/bryan-gilliom.md new file mode 100644 index 0000000..c889acc --- /dev/null +++ b/resources/people/bryan-gilliom.md @@ -0,0 +1,42 @@ +--- +type: person +status: active +created: 2026-06-02 +updated: 2026-06-02 +tags: [person, primary-operator] +agent_written: true +source_notes: [] +company: Message Point Media (MPM) +role: CEO +last_contact: +--- + +# Bryan Gilliom + +## Who They Are + +CEO of Message Point Media (MPM) and the **primary user** of this memory vault. This vault exists to serve as Bryan's persistent second brain across Claude/CoWork sessions — the system of record for his context, decisions, projects, and preferences. + +## Relationship Context + +- **Primary operator** — default "the operator" in agent memory and preferences refers to Bryan unless stated otherwise. +- [[resources/people/jason-stedwell]] is the architect and creator of the vault, and a possible future collaborator — not the day-to-day user. + +## Working Preferences + +_To be learned and recorded as evidence accumulates. Do not fabricate — capture only what is observed or stated, then promote durable patterns to [[_agent/memory/semantic/operator-preferences]]._ + +## Recent Interactions + +- _None recorded yet._ + +## Open Follow-Ups + +- Confirm Bryan's preferred communication style, output formats, and recurring workflows. +- Identify the active projects and areas Bryan wants tracked first. +- Confirm which connectors/tools Bryan relies on (MPM systems, email, calendar, etc.). + +## Related + +- [[resources/people/jason-stedwell]] +- [[_agent/memory/semantic/operator-preferences]] diff --git a/resources/people/jason-stedwell.md b/resources/people/jason-stedwell.md new file mode 100644 index 0000000..a332f87 --- /dev/null +++ b/resources/people/jason-stedwell.md @@ -0,0 +1,38 @@ +--- +type: person +status: active +created: 2026-06-01 +updated: 2026-06-01 +tags: [person] +agent_written: false +source_notes: [] +company: MPM / ALABAMA wISP +role: Director of Technical Services / Systems Engineer +last_contact: 2026-06-01 +--- + +# Jason Stedwell + +## Who They Are + +Primary designer of this memory vault system. + +## Relationship Context + +Designed the structure, workflow, and future plugin direction for this vault. + +## Recent Interactions + +- Requested starter vault scaffold and documentation-first setup. + +## Open Follow-Ups + +- Confirm plugin CRUD priorities. +- Confirm desired startup/shutdown agent hooks. + +## Related Projects + +- [[projects/active/vault-foundation]] + +## Related +- [[projects/active/vault-foundation]] diff --git a/resources/references/obsidian-local-rest-api.md b/resources/references/obsidian-local-rest-api.md new file mode 100644 index 0000000..cf91bd0 --- /dev/null +++ b/resources/references/obsidian-local-rest-api.md @@ -0,0 +1,245 @@ +--- +type: reference +status: active +created: 2026-06-01 +updated: 2026-06-02 +tags: [reference, api, obsidian, rest, plugin] +agent_written: true +source_notes: [] +--- + +# Obsidian Local REST API + +## Summary +This is the operational command reference for reaching the **goldbrain** vault over the +[Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api). +It is the contract a CoWork plugin or any REST client follows to read and write memory. +Paths address the vault **at its root** (e.g. `/vault/_agent/...`), matching the layout +defined in STRUCTURE and verified by BOOTSTRAP. + +## Connection + +| Setting | Value | +|---------|-------| +| Base URL | `https://goldbrainapi.mpm.to` | +| Auth | `Authorization: Bearer ` on every request | +| Content type (writes) | `text/markdown` (or `application/json` for frontmatter patches) | + +**Never store the key in the vault.** It lives in the local environment / plugin config, +not in any note. The examples below read it from the shell: + +```bash +export OBSIDIAN_REST_API_URL="https://goldbrainapi.mpm.to" +export OBSIDIAN_REST_API_KEY="" +AUTH="Authorization: Bearer ${OBSIDIAN_REST_API_KEY}" +BASE="${OBSIDIAN_REST_API_URL}" +``` + +> TLS note: `goldbrainapi.mpm.to` presents a valid certificate (reverse proxy → +> `192.168.86.15:27124`), so `-k` is **not** needed. Add `-k` only if the endpoint is ever +> switched to a self-signed certificate. + +--- + +## Reading Files + +```bash +curl -s -H "$AUTH" "$BASE/vault/_agent/context/current-context.md" +``` + +Returns raw file content (`text/markdown`). A `404` means the file does not exist. + +```bash +# Read only one heading's content (full heading path, :: delimited) +curl -s -H "$AUTH" \ + "$BASE/vault/_agent/memory/semantic/operator-preferences.md/heading/Operator%20Preferences%3A%3AFact%20%2F%20Pattern" +``` + +--- + +## Listing Directories + +```bash +curl -s -H "$AUTH" "$BASE/vault/_agent/sessions/" # trailing slash required +``` + +Returns JSON: `{ "files": [...], "folders": [...] }`. + +--- + +## Appending Content (POST) + +`POST` appends to the **end** of an existing file; it creates the file if absent. + +```bash +cat > /tmp/obs_entry.md << 'OBSEOF' +- 2026-06-02: quick note to triage later +OBSEOF + +curl -s -X POST -H "$AUTH" -H "Content-Type: text/markdown" \ + --data-binary @/tmp/obs_entry.md \ + "$BASE/vault/inbox/captures/inbox.md" +``` + +--- + +## Creating or Overwriting Files (PUT) + +`PUT` creates a new file or fully overwrites one. Missing parent directories are created automatically. + +```bash +cat > /tmp/obs_file.md << 'OBSEOF' +--- +type: session-log +status: complete +created: 2026-06-02 +updated: 2026-06-02 +tags: [] +agent_written: true +source_notes: [] +--- + +# Session: + +## Related +- [[projects/active/some-project]] +OBSEOF + +curl -s -X PUT -H "$AUTH" -H "Content-Type: text/markdown" \ + --data-binary @/tmp/obs_file.md \ + "$BASE/vault/_agent/sessions/2026-06-02-1430-my-session.md" +``` + +Include the canonical frontmatter (see STRUCTURE / BOOTSTRAP §4) and set `agent_written: true` +on agent-generated notes. Cross-reference links go in a body `## Related` section, never in frontmatter. + +--- + +## Patching a Specific Section (PATCH) + +`PATCH` edits inside a file without rewriting it. Target and operation are set via headers. + +### Append under a heading + +**Heading targets must be the FULL heading path, `::`-delimited from the top-level heading.** +A bare subheading name returns `400 invalid-target` (errorCode 40080). Verified against +API v4.1.2. Example: `## Fact / Pattern` under `# Operator Preferences` → +`Target: Operator Preferences::Fact / Pattern`. Percent-encode non-ASCII; spaces are fine. + +```bash +cat > /tmp/obs_patch.md << 'OBSEOF' +Bryan prefers concise status updates — lead with the decision. +OBSEOF + +curl -s -X PATCH -H "$AUTH" \ + -H "Operation: append" \ + -H "Target-Type: heading" \ + -H "Target: Operator Preferences::Fact / Pattern" \ + -H "Content-Type: text/markdown" \ + --data-binary @/tmp/obs_patch.md \ + "$BASE/vault/_agent/memory/semantic/operator-preferences.md" +``` + +To discover exact heading paths, GET the note with `Accept: application/vnd.olrapi.document-map+json`; +it returns `{ "headings": [...], "blocks": [...], "frontmatterFields": [...] }` — copy the +heading string verbatim into `Target`. + +### Replace a heading's content entirely + +Same call with `Operation: replace` — e.g. to refresh a project's `Project Name::Current status`. + +### Prepend under a heading + +Same call with `Operation: prepend`. + +### Patch a frontmatter field + +```bash +curl -s -X PATCH -H "$AUTH" \ + -H "Operation: replace" \ + -H "Target-Type: frontmatter" \ + -H "Target: updated" \ + -H "Content-Type: application/json" \ + --data '"2026-06-02"' \ + "$BASE/vault/projects/active/vault-foundation.md" +``` + +Use this to keep `updated:` and `status:` current after a write. + +--- + +## Searching + +```bash +curl -s -X POST -H "$AUTH" "$BASE/search/simple/?query=weekly+review" +``` + +Returns an array of `{ filename, score, matches: [{ context, match }] }`. + +--- + +## Deleting Files + +```bash +curl -s -X DELETE -H "$AUTH" "$BASE/vault/archive/notes/old-note.md" +``` + +Only on an explicit request. Deletion is destructive; memory is append-friendly. + +--- + +## URL-Encoding Notes + +- Path separators (`/`) in the vault path are **literal** — do not encode them. +- Spaces in filenames or heading targets in a URL: use `%20`. +- Nested heading levels in a URL path: use `%3A%3A` for `::`. +- Heading text in the `Target:` header: the **full heading path** joined by `::` (e.g. `Operator Preferences::Fact / Pattern`), no `#`; spaces fine; percent-encode non-ASCII. + +--- + +## Memory Routing Map + +Where each kind of write lands in goldbrain (mirrors BOOTSTRAP §3 and the taxonomy in STRUCTURE). + +| Situation | Vault path | Method | +|-----------|-----------|--------| +| Unsorted / quick capture | `inbox/captures/inbox.md` (date-prefixed line) | POST | +| Raw imported material | `inbox/imports/` | PUT | +| Operator preference / durable fact | `_agent/memory/semantic/operator-preferences.md` | PATCH | +| Other durable facts, patterns | `_agent/memory/semantic/<slug>.md` | PUT | +| Event record (what happened) | `_agent/memory/episodic/<slug>.md` | PUT | +| Short-lived, time-boxed state | `_agent/memory/working/<slug>.md` | PUT | +| Task-scoped context / focus | `_agent/context/current-context.md` | PATCH / PUT | +| Working-session log | `_agent/sessions/YYYY-MM-DD-HHMM-<slug>.md` | PUT | +| Long-running project state | `projects/active/<slug>.md` | PUT + PATCH | +| Non-obvious decision (ADR) | `decisions/by-date/YYYY-MM-DD-<slug>.md` (mirror `by-project/`) | PUT | +| Person context | `resources/people/<name>.md` | PUT / PATCH | +| Concept / reference note | `resources/concepts/` or `resources/references/` | PUT | +| Daily activity / Agent Log | `journal/daily/YYYY-MM-DD.md` | POST / PATCH | +| Periodic review | `reviews/{weekly,monthly,quarterly,annual}/` | PUT | + +**Slug rules:** kebab-case, ASCII, ~40 chars max. Every file carries canonical frontmatter (no `[[wikilinks]]` in it). + +--- + +## Plugin Readiness Checklist + +- [ ] Base URL reachable; returns `401` without the key, content with it. +- [ ] `GET /vault/BOOTSTRAP.md` succeeds (vault bootstrapped — else run BOOTSTRAP). +- [ ] A test `PUT` into `_agent/sessions/` creates the file and parent dirs. +- [ ] A `PATCH` `Target-Type: heading` append with a full `::` path lands under the right heading. +- [ ] `POST /search/simple/?query=...` returns scored matches. +- [ ] Key supplied via env / plugin config only — never written into a note. + +## Sources / Notes +Adapted from the working `obsidian-memory` plugin reference, retargeted to goldbrain's +vault-root layout and the `goldbrainapi.mpm.to` host. Record host-binding or plugin-specific +conventions here as they emerge. + +## Related +- [[spinup]] +- [[BOOTSTRAP]] +- [[STRUCTURE]] +- [[CLAUDE]] +- [[_agent/context/current-context]] +- [[projects/active/vault-foundation]] diff --git a/resources/source-material/README.md b/resources/source-material/README.md new file mode 100644 index 0000000..a2b7bbf --- /dev/null +++ b/resources/source-material/README.md @@ -0,0 +1,5 @@ +# source-material/ + +Raw source documents and references to process. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/reviews/annual/README.md b/reviews/annual/README.md new file mode 100644 index 0000000..742849d --- /dev/null +++ b/reviews/annual/README.md @@ -0,0 +1,5 @@ +# annual/ + +Annual reviews. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/reviews/monthly/README.md b/reviews/monthly/README.md new file mode 100644 index 0000000..cb1f582 --- /dev/null +++ b/reviews/monthly/README.md @@ -0,0 +1,5 @@ +# monthly/ + +Monthly reviews. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/reviews/quarterly/README.md b/reviews/quarterly/README.md new file mode 100644 index 0000000..e402ce1 --- /dev/null +++ b/reviews/quarterly/README.md @@ -0,0 +1,5 @@ +# quarterly/ + +Quarterly reviews. + +> Placeholder so this folder persists (empty dirs are dropped by file copies and git). Safe to delete once the folder has real content. diff --git a/reviews/weekly/2026-W23.md b/reviews/weekly/2026-W23.md new file mode 100644 index 0000000..11f7639 --- /dev/null +++ b/reviews/weekly/2026-W23.md @@ -0,0 +1,37 @@ +--- +type: review +status: active +created: 2026-W23 +updated: 2026-W23 +tags: [review, weekly] +agent_written: true +source_notes: [] +period: weekly +--- + +# Weekly Review + +## Completed Work +- Created the starter memory vault scaffold. + +## Open Loops +- Review and refine all templates. +- Add plugin-facing contracts. + +## Stale Projects +- None yet. + +## Decisions +- Root docs will define vault behavior. +- `_agent/` will hold operational agent state. + +## Priorities Next Week +- Add plugin spec. +- Add startup/shutdown automation docs. + +## Agent Notes +Use this note to promote important observations into semantic memory. + +## Related +- [[journal/daily/2026-06-01]] +- [[projects/active/vault-foundation]] diff --git a/spinup.md b/spinup.md new file mode 100644 index 0000000..2880ed6 --- /dev/null +++ b/spinup.md @@ -0,0 +1,29 @@ +# spinup.md + +## Purpose + +This guide is the complete user (not agent) spin-up walkthrough for taking a fresh Obsidian vault from empty folder to live operational memory system for Claude Code, with a path toward future CoWork plugin integration through the Obsidian Local REST API. + +## High-Level Flow + +- [x] 1. Create the vault. +- [x] 2. Add root operating docs. +- [x] 3. Build the folder tree. +- [x] 4. Add templates. +- [x] 5. Create initial notes. +- [ ] 6. Validate Claude Code access. +- [x] 7. Enable the Obsidian Local REST API. +- [ ] 8. Start the daily/session/review operating rhythm. + +## Verified status — 2026-06-02 + +Checked against the live vault at `goldbrainapi.mpm.to` after the scaffold copy. + +- **1. Create the vault** — Done. Vault is live and reachable via the REST API. +- **2. Add root operating docs** — Done. `CLAUDE.md`, `BOOTSTRAP.md`, `STRUCTURE.md`, `spinup.md`, `index.md`, `README.md`, and `.env.example` all present. +- **3. Build the folder tree** — Done. Full tree present and verified over the API. The empty subfolders that file-copy dropped (`inbox/imports`, `inbox/processing-log`, `journal/weekly`, `journal/monthly`, `projects/incubating`, `projects/on-hold`, `projects/archived`, `areas/personal`, `resources/meetings`, `resources/source-material`, `decisions/by-date`, `decisions/by-project`, `reviews/monthly`, `reviews/quarterly`, `reviews/annual`, `archive/notes`, `archive/projects`, `archive/imports`, `_agent/memory/episodic`, `_agent/outputs/{briefs,drafts,summaries,synthesis}`, `_agent/skills/archived`) were recreated with a placeholder `README.md` in each so they persist. +- **4. Add templates** — Done. All eight templates present (`_agent/templates/*`, `journal/templates/*`, `projects/project-template.md`, `decisions/decision-template.md`). +- **5. Create initial notes** — Done. Seed/anchor notes present (`current-context.md`, `operator-preferences.md`, `active-setup.md`, initial session log, daily note, people notes, etc.). +- **6. Validate Claude Code access** — Not yet verified. Confirm Claude Code can read/write the vault folder directly on the host. +- **7. Enable the Obsidian Local REST API** — Done. Verified end-to-end: API v4.1.2 responds through the reverse proxy with a valid TLS cert, the bearer key authenticates, and a write → read → list → delete round-trip succeeded. +- **8. Start the daily/session/review operating rhythm** — Not yet. Begins once the operator starts using the vault day-to-day.