# GitHub Copilot Instructions for Memory Palace

## Project Overview

This is a hybrid workspace combining:

- **Documentation**: Obsidian-style knowledge management with wiki-links and backlinks
- **Code Development**: Bookmarklets, scratchpad code, and project prototypes

## Documentation Guidelines

### Writing Style

- Use clear, concise markdown
- Employ wiki-style `[[links]]` for connecting notes
- Include frontmatter metadata in notes (date, type, tags)
- Keep daily notes in `/docs/daily/` with format `daily-YYYY-MM-DD.md`
- Place evergreen concept notes in `/docs/concepts/`

### Note Structure

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

# Title

## Overview

Brief summary

## Content

Main content with [[links]]

## Related

- [[other-note]]
```

## Code Development Guidelines

### Bookmarklets (`/code/bookmarklets/`)

- Write as regular Node.js-compatible JavaScript files
- Use modern ES6+ syntax, let/const, etc. (will be minified)
- Include JSDoc comments for documentation (removed in final bookmarklet)
- Write clear, readable code - the generator handles minification
- Use descriptive variable and function names
- Test logic in Node.js if possible before converting

**Conversion Process:**

1. Write bookmarklet as normal `.js` file in `/code/bookmarklets/`
2. Run: `npm run bookmarklet -- code/bookmarklets/your-file.js`
3. Generator automatically:
   - Removes all comments
   - Minifies code
   - Wraps in IIFE: `javascript:(function(){...})();`
   - Copies to clipboard
4. Paste into browser bookmark URL field

### Scratchpad Code (`/code/scratchpad/`)

- This is experimental space - be creative
- Add `TODO:` comments for work in progress
- Use descriptive variable names
- Include usage examples
- Python: Follow PEP 8 style
- JavaScript/TypeScript: Use modern ES6+ syntax

### Code Style

- **Python**: PEP 8, type hints preferred
- **JavaScript**: Modern ES6+, const/let over var, **ES modules (import/export)**
- **TypeScript**: Explicit types, interfaces over types
- Comments: Explain _why_, not _what_
- Functions: Single responsibility, descriptive names

### Module System

**This project uses ES modules (import/export), not CommonJS (require).**

- Use `import` for dependencies: `import fs from 'fs';`
- Use `export` for exporting: `export default myFunction;` or `export { myFunction };`
- Package.json is configured with `"type": "module"`
- Use `.js` extension for ES modules
- For Node.js built-ins requiring special handling: `import { fileURLToPath } from 'url';`

## File Organization

### When to Create Files

- **Fleeting notes**: Quick captures, temporary thoughts → `/docs/fleeting/`
- **Concept notes**: Refined ideas, evergreen content → `/docs/concepts/`
- **Project docs**: Specific project documentation → `/docs/projects/`
- **Bookmarklets**: Browser utilities → `/code/bookmarklets/`
- **Experiments**: Testing/learning → `/code/scratchpad/`

### Naming Conventions

- Documentation: `kebab-case.md` (e.g., `my-note.md`)
- JavaScript: `kebab-case.js` (e.g., `my-bookmarklet.js`)
- Python: `snake_case.py` (e.g., `my_script.py`)
- TypeScript: `kebab-case.ts` (e.g., `my-module.ts`)

## Git Commit Practices

GitDoc auto-commits on save. For manual commits:

- Use conventional commits: `type: description`
- Types: `docs:`, `feat:`, `fix:`, `refactor:`, `chore:`
- Examples:
  - `docs: add note on memory techniques`
  - `feat: create bookmark highlighter bookmarklet`
  - `fix: correct regex in search bookmarklet`

## Special Considerations

### Cross-Linking

When suggesting note connections:

- Look for conceptual relationships
- Suggest bidirectional links
- Consider creating index notes for related topics

### Code Reusability

- Create templates in `/code/templates/` for common patterns
- Extract reusable functions into utility modules
- Document APIs and interfaces

### Search & Discovery

- Use descriptive titles and headers
- Include relevant tags in frontmatter
- Add aliases for alternative terms
- Consider TODO tags: `TODO:`, `FIXME:`, `NOTE:`, `IDEA:`

## Preferences

- **Brevity**: Favor concise, clear explanations
- **Examples**: Include practical examples in code
- **Context**: Assume this is a personal knowledge workspace
- **Flexibility**: This is a scratchpad - prioritize exploration over perfection
- **Learning**: Explain concepts when introducing new patterns or techniques

## README Maintenance

**IMPORTANT**: Keep README files synchronized with project structure changes.

### When to Update READMEs

Update relevant README.md files whenever you:

- Add or remove folders
- Change file organization
- Add new tools or utilities
- Modify workflows or conventions
- Add new features or capabilities

### README Locations

- `/README.md` - Main project overview and quick start
- `/docs/README.md` - Documentation hub and note-taking guide
- `/code/README.md` - Code section overview
- `/code/bookmarklets/README.md` - Bookmarklet creation guide
- `/.github/README.md` - GitHub templates and structure

### Update Guidelines

- Keep structure diagrams accurate
- Update examples to reflect current patterns
- Maintain consistency across all READMEs
- Add new sections before implementation when adding major features
- Remove outdated information immediately

## Tools & Extensions Available

- Foam (wiki-links, backlinks, graph)
- Code Runner (quick code execution)
- Todo Tree (tracks TODO comments)
- Bookmarks (mark important code locations)
- ESLint (JavaScript linting)