memory-infrastructure-palace/.github/copilot-instructions.md

GitHub Copilot Instructions for Memory Palace

MUST FOLLOW

Do not run commands in the same terminal where the server was started. Always open a new terminal for running new commands or tests if the active terminal has a long-running process.

Project Overview

Hybrid workspace combining Obsidian-style knowledge management with code development. Uses Obsidian MD for VSCode extension (wiki-links, backlinks, graph view) alongside JavaScript/Python development tools.

Architecture: Documentation lives in /docs, code in /code. GitDoc auto-commits on save (1s delay), auto-pushes after commit.

Dual Obsidian Vaults: Both /docs/projects/memorypalace/ and /docs/projects/pokemon-professor/ are independent Obsidian vaults edited in both native Obsidian and VS Code. These contain rich project-specific knowledge that can inform code implementations and provide context for related development work.

Critical Workflows

Bookmarklet Development

Never use CommonJS or require() - this project uses ES modules exclusively.

1. Write bookmarklets as regular, readable JavaScript in /code/bookmarklets/
2. Include JSDoc comments (they're stripped during generation)
3. Run: npm run bookmarklet -- code/bookmarklets/your-file.js
4. Generator (code/utils/bookmarkletMaker.js) handles:
   • Comment removal (single/multi-line)
   • Code minification
   • IIFE wrapping: javascript:(function(){...})();
   • Clipboard copying

Example bookmarklet structure:

/**
 * My Bookmarklet - Description
 */
const elements = document.querySelectorAll('a');
elements.forEach(el => {
  el.style.backgroundColor = 'yellow';
});
alert(`Found ${elements.length} links!`);

Documentation Workflow

Notes use Obsidian frontmatter and wiki-linking:

---
type: concept|project|fleeting
created: YYYY-MM-DD
tags: []
---

# Title
Content with [[wiki-links]]

File locations by type:

• Quick captures → /docs/fleeting/
• Refined concepts → /docs/concepts/
• Project docs → /docs/projects/
• Daily notes → /docs/daily/ (format: daily-YYYY-MM-DD.md)

Module System (CRITICAL)

ES modules only - package.json has "type": "module":

// ✅ Correct
import fs from 'fs';
import { fileURLToPath } from 'url';
export default myFunction;
export { helperFunction };

// ❌ Never use
const fs = require('fs');
module.exports = myFunction;

Project-Specific Conventions

File Naming

• Markdown: kebab-case.md
• JavaScript: kebab-case.js
• Python: snake_case.py
• Templates in /code/templates/ show module patterns

Git Commits

GitDoc auto-commits, but for manual commits use conventional format:

• docs: - Documentation changes
• feat: - New features
• fix: - Bug fixes
• refactor: - Code restructuring
• chore: - Maintenance

Code Organization

• /code/bookmarklets/ - Browser utilities (final destination)
• /code/scratchpad/ - Experiments, organized by language
• /code/junk-drawer/ - WIP items, miscellaneous scripts
• /code/templates/ - Reusable patterns (ES module examples)
• /code/utils/ - Build tools (bookmarklet generator, README updater)

README Synchronization

Update READMEs when changing structure - multiple READMEs mirror folder organization:

• /README.md - Main overview
• /docs/README.md - Documentation guide
• /code/README.md - Code overview
• /code/bookmarklets/README.md - Bookmarklet guide

Extensions & Tools Context

Workspace configured for:

• Obsidian MD for VSCode - wiki-links, graph view, daily notes
• Code Runner - Execute Python/JS/TS directly (runInTerminal: true)
• Todo Tree - Tracks TODO, FIXME, NOTE, IDEA, HACK, QUESTION tags
• GitDoc - Auto-commit delay 1000ms, pulls on open
• Settings in .vscode/settings.json override defaults

Key Implementation Details

Auto-Save & GitDoc

Files auto-save after 1s (files.autoSaveDelay: 1000), GitDoc commits 1s after save. Changes are pushed automatically - no manual git commands needed during normal workflow.

Code Execution

Code Runner configured with:

• JavaScript: node (ES module compatible)
• Python: python3
• TypeScript: ts-node
• Always saves file before running

Obsidian Configuration

• Vault path: root workspace directory
• Daily notes: docs/daily/daily-YYYY-MM-DD.md
• New notes: docs/ by default
• Attachments: docs/assets/

Development Preferences

• Exploration over perfection - This is a personal scratchpad
• Document why, not what - Code should be self-explanatory
• Practical examples - Include usage examples in code
• Cross-link liberally - Wiki-links create knowledge connections
• Track todos inline - Use TODO/FIXME/NOTE comments (Todo Tree finds them)