@orderful/droid 0.10.2 → 0.10.4

package/dist/skills/comments/SKILL.md

@@ -31,21 +31,23 @@ The AI will respond with `> @{user_mention}` (configured in droid setup, e.g., `
 **CRITICAL: The `@mention` is who you're talking TO, not who is speaking.**
 
 Think of it like addressing someone in conversation:
+
 - "Hey @droid, what do you think?" → User talking TO the AI
 - "Good point @fry, here's my take..." → AI talking TO the user
 
 | When you see... | Who wrote it | Who it's addressed to |
-|-----------------|--------------|----------------------|
-| `> @droid ...`  | User         | AI (droid)           |
-| `> @fry ...`    | AI           | User (fry)           |
+| --------------- | ------------ | --------------------- |
+| `> @droid ...`  | User         | AI (droid)            |
+| `> @fry ...`    | AI           | User (fry)            |
 
 **Examples:**
+
 ```markdown
-> @droid Can you explain this function?     ← User asking AI
+> @droid Can you explain this function? ← User asking AI
 > @fry This function calculates the hash... ← AI responding to user
 
-> @droid Should we refactor this?           ← User asking AI
-> @fry Yes, I'd suggest extracting...       ← AI responding to user
+> @droid Should we refactor this? ← User asking AI
+> @fry Yes, I'd suggest extracting... ← AI responding to user
 ```
 
 **Never flip this.** When responding to a `@droid` comment, always use `@{user}` (e.g., `@fry`) because you're addressing the user, not yourself.
@@ -76,13 +78,19 @@ When you find a `@droid` marker:
 ## Behavior
 
 ### On `/comments check`:
-1. Search for `> @droid` (and any configured `ai_mentions`) in the specified scope
-2. If there's a `git diff`, check those files first for relevant context
-3. For each comment, determine intent:
-   - **Action request** ("do X", "add Y", "fix Z") → Execute the action, remove the comment
-   - **Question** ("what do you think", "should we") → Respond with `> @{user_mention}`, keep original comment
+
+1. **Read config first:** Check `~/.droid/skills/comments/overrides.yaml` for `preserve_comments` setting (default: `true`)
+2. Search for `> @droid` (and any configured `ai_mentions`) in the specified scope
+3. If there's a `git diff`, check those files first for relevant context
+4. For each comment, determine intent:
+   - **Action request** ("do X", "add Y", "fix Z") → Execute the action
+   - **Question** ("what do you think", "should we") → Respond with `> @{user_mention}`
+5. **Handle original comment based on `preserve_comments`:**
+   - If `preserve_comments: true` → Keep the original `@droid` comment (add response below it)
+   - If `preserve_comments: false` → Remove the original comment after addressing
 
 ### On `/comments cleanup`:
+
 1. Find AI tag and `> @{user_mention}` pairs where conversation appears resolved
 2. Remove both markers
 3. Output a summary of what was discussed/decided

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {

package/src/commands/setup.ts

@@ -240,11 +240,9 @@ export async function setupCommand(): Promise<void> {
       name: 'user_mention',
       message: 'What @mention should be used for you?',
       default: '@user',
-      validate: (input: string) => {
-        if (!input.startsWith('@')) {
-          return 'Mention should start with @';
-        }
-        return true;
+      filter: (input: string) => {
+        // Auto-add @ prefix if missing
+        return input.startsWith('@') ? input : `@${input}`;
       },
     },
     {

package/src/commands/tui.tsx

@@ -23,7 +23,7 @@ import { getRandomQuote } from '../lib/quotes.js';
 
 type Tab = 'skills' | 'commands' | 'agents' | 'settings';
 type View = 'welcome' | 'setup' | 'menu' | 'detail' | 'configure' | 'readme';
-type SetupStep = 'ai_tool' | 'user_mention' | 'output_preference' | 'confirm';
+type SetupStep = 'ai_tool' | 'user_mention' | 'confirm';
 
 const colors = {
   primary: '#6366f1',
@@ -331,9 +331,6 @@ function SetupScreen({ onComplete, onSkip, initialConfig }: SetupScreenProps) {
     initialConfig?.ai_tool || getDefaultAITool()
   );
   const [userMention, setUserMention] = useState(initialConfig?.user_mention || '@user');
-  const [outputPreference, setOutputPreference] = useState<OutputPreference>(
-    initialConfig?.output_preference || BuiltInOutput.Terminal
-  );
   const [selectedIndex, setSelectedIndex] = useState(0);
   const [error, setError] = useState<string | null>(null);
 
@@ -343,20 +340,17 @@ function SetupScreen({ onComplete, onSkip, initialConfig }: SetupScreenProps) {
     { label: 'Claude Code', value: AITool.ClaudeCode },
     { label: 'OpenCode', value: AITool.OpenCode },
   ], []);
-  const outputOptions = useMemo(() => getOutputOptions(), []);
 
-  const steps: SetupStep[] = ['ai_tool', 'user_mention', 'output_preference', 'confirm'];
+  const steps: SetupStep[] = ['ai_tool', 'user_mention', 'confirm'];
   const stepIndex = steps.indexOf(step);
   const totalSteps = steps.length - 1; // Don't count confirm as a step
 
   const handleUserMentionSubmit = () => {
-    if (!userMention.startsWith('@')) {
-      setError('Mention should start with @');
-      return;
-    }
+    // Auto-add @ prefix if missing
+    const mention = userMention.startsWith('@') ? userMention : `@${userMention}`;
+    setUserMention(mention);
     setError(null);
-    setStep('output_preference');
-    setSelectedIndex(0);
+    setStep('confirm');
   };
 
   // Handle escape during text input (only intercept escape, nothing else)
@@ -372,11 +366,8 @@ function SetupScreen({ onComplete, onSkip, initialConfig }: SetupScreenProps) {
     if (key.escape) {
       if (step === 'ai_tool') {
         onSkip();
-      } else if (step === 'output_preference') {
-        setStep('user_mention');
       } else if (step === 'confirm') {
-        setStep('output_preference');
-        setSelectedIndex(0);
+        setStep('user_mention');
       }
       return;
     }
@@ -388,20 +379,13 @@ function SetupScreen({ onComplete, onSkip, initialConfig }: SetupScreenProps) {
         setAITool(aiToolOptions[selectedIndex].value);
         setStep('user_mention');
       }
-    } else if (step === 'output_preference') {
-      if (key.upArrow) setSelectedIndex((prev) => Math.max(0, prev - 1));
-      if (key.downArrow) setSelectedIndex((prev) => Math.min(outputOptions.length - 1, prev + 1));
-      if (key.return) {
-        setOutputPreference(outputOptions[selectedIndex].value);
-        setStep('confirm');
-      }
     } else if (step === 'confirm') {
       if (key.return) {
         const config: DroidConfig = {
           ...loadConfig(),
           ai_tool: aiTool,
           user_mention: userMention,
-          output_preference: outputPreference,
+          output_preference: BuiltInOutput.Terminal, // Default to terminal
         };
         saveConfig(config);
         configureAIToolPermissions(aiTool);
@@ -471,26 +455,6 @@ function SetupScreen({ onComplete, onSkip, initialConfig }: SetupScreenProps) {
     );
   }
 
-  if (step === 'output_preference') {
-    return (
-      <Box flexDirection="column" padding={1}>
-        {renderHeader()}
-        <Text color={colors.text}>Default output preference for skill results?</Text>
-        <Box flexDirection="column" marginTop={1}>
-          {outputOptions.map((option, index) => (
-            <Text key={option.value}>
-              <Text color={colors.textDim}>{index === selectedIndex ? '>' : ' '} </Text>
-              <Text color={index === selectedIndex ? colors.text : colors.textMuted}>{option.label}</Text>
-            </Text>
-          ))}
-        </Box>
-        <Box marginTop={1}>
-          <Text color={colors.textDim}>↑↓ select · enter next · esc back</Text>
-        </Box>
-      </Box>
-    );
-  }
-
   // Confirm step
   return (
     <Box flexDirection="column" padding={1}>
@@ -505,10 +469,6 @@ function SetupScreen({ onComplete, onSkip, initialConfig }: SetupScreenProps) {
           <Text color={colors.textDim}>Your @mention: </Text>
           <Text color={colors.text}>{userMention}</Text>
         </Text>
-        <Text>
-          <Text color={colors.textDim}>Output:        </Text>
-          <Text color={colors.text}>{outputOptions.find((o) => o.value === outputPreference)?.label || outputPreference}</Text>
-        </Text>
       </Box>
       <Box marginTop={2}>
         <Text backgroundColor={colors.primary} color="#ffffff" bold>
@@ -1042,12 +1002,6 @@ function SettingsDetails({
           <Text color={colors.textDim}>Your @mention: </Text>
           <Text color={colors.text}>{config.user_mention}</Text>
         </Text>
-        <Text>
-          <Text color={colors.textDim}>Output:        </Text>
-          <Text color={colors.text}>
-            {outputOptions.find((o) => o.value === config.output_preference)?.label || config.output_preference}
-          </Text>
-        </Text>
       </Box>
 
       <Box marginTop={1}>
@@ -1399,8 +1353,6 @@ function App() {
   useInput((input, key) => {
     if (message) setMessage(null);
 
-    if (view === 'welcome') return;
-
     if (input === 'q') {
       exit();
       return;
@@ -1610,7 +1562,7 @@ function App() {
         }
       }
     }
-  });
+  }, { isActive: view !== 'welcome' && view !== 'setup' && view !== 'configure' });
 
   const selectedSkill = activeTab === 'skills' ? skills[selectedIndex] ?? null : null;
   const selectedCommand = activeTab === 'commands' ? commands[selectedIndex] ?? null : null;

package/src/skills/brain/SKILL.md

@@ -38,31 +38,48 @@ Ideas develop through iteration, not single prompts.
 
 **IMPORTANT:** Before using any default paths, ALWAYS read `~/.droid/skills/brain/overrides.yaml` first. If `brain_dir` is configured there, use that path. Only fall back to defaults if the file doesn't exist or lacks a `brain_dir` setting.
 
-| Setting        | Default     | Description                                               |
-| -------------- | ----------- | --------------------------------------------------------- |
-| `brain_dir`    | (see below) | Where docs are stored                                     |
-| `inbox_folder` | (empty)     | Optional subfolder for new docs (omit for flat structure) |
+| Setting        | Default     | Description                                   |
+| -------------- | ----------- | --------------------------------------------- |
+| `brain_dir`    | (see below) | Where docs are stored                         |
+| `inbox_folder` | (empty)     | Root folder for new docs (e.g., `0-Inbox`)    |
 
 Default `brain_dir` by AI tool (only if not configured):
 
 - **claude-code**: `~/.claude/brain`
 - **opencode**: `~/.config/opencode/brain`
 
+## Folder Structure
+
+Docs are organized by type into subfolders:
+
+```
+{brain_dir}/
+└── {inbox_folder}/     # e.g., "0-Inbox" (or root if not set)
+    ├── plans/          # Structured planning docs
+    ├── research/       # Open-ended exploration
+    ├── reviews/        # Code reviews, evaluations
+    └── ideas/          # Quick captures
+```
+
+Folders are created automatically when needed.
+
 ## Core Concepts
 
 **Active doc:** Opening or creating a brain doc makes it "active" for the session. Subsequent `/brain add` commands append to it without specifying a path.
 
-**Doc types:**
+**Doc types:** (each stored in its own folder)
 
-- `plan` - Structured: Context → Exploration → Decision → Next Steps
-- `research` - Open-ended exploration of a topic
-- `review` - Code review, document review, or any evaluation task
-- `note` - Quick capture (fire-and-forget, doesn't become active)
+- `plan` → `plans/` - Structured: Context → Exploration → Decision → Next Steps
+- `research` → `research/` - Open-ended exploration of a topic
+- `review` → `reviews/` - Code review, document review, or any evaluation task
+- `idea` → `ideas/` - Quick capture (fire-and-forget, doesn't become active)
 
 **Comment conventions:** In markdown files, ALWAYS use blockquote `>` prefix for @mention comments:
 
-- `> @droid` - User leaves comment for AI to address
-- `> @{user}` - AI leaves comment for user to address
+- `> @droid` - **User** leaves comment for AI to address
+- `> @{user}` - **AI** leaves comment for user to address
+
+**CRITICAL:** When YOU (the AI) respond to a comment or create a placeholder, you MUST use `> @{user_mention}` (e.g., `> @fry`). NEVER use `@droid` for your own responses - that tag is for the USER to address YOU.
 
 Example conversation:
 
@@ -82,10 +99,10 @@ Read user's configured mention from `~/.droid/config.yaml` → `user_mention` (e
 | ------------------------- | ---------------------------------------------------------- |
 | `/brain`                  | List recent docs or create new                             |
 | `/brain {topic}`          | **Search** for existing doc (fuzzy match) → becomes active |
-| `/brain plan {topic}`     | Create planning doc (requires `plan` keyword)              |
-| `/brain research {topic}` | Create research doc (requires `research` keyword)          |
-| `/brain review {topic}`   | Create review doc (requires `review` keyword)              |
-| `/brain note {text}`      | Quick capture (standalone, doesn't become active)          |
+| `/brain plan {topic}`     | Create planning doc → `plans/{topic}.md`                   |
+| `/brain research {topic}` | Create research doc → `research/{topic}.md`                |
+| `/brain review {topic}`   | Create review doc → `reviews/{topic}.md`                   |
+| `/brain idea {text}`      | Quick capture → `ideas/{date}-{slug}.md` (not active)      |
 | `/brain add {text}`       | Append to active doc                                       |
 | `/brain check`            | Address @droid comments in active doc                      |
 | `/brain done`             | Finalize active doc, update status                         |
@@ -110,13 +127,13 @@ Full procedure: `references/workflows.md` § Creating
 Templates: `references/templates.md`
 Naming: `references/naming.md`
 
-## Quick Notes
+## Quick Ideas
 
-**Trigger:** `/brain note {text}`
+**Trigger:** `/brain idea {text}`
 
-**TLDR:** Fire-and-forget capture to inbox. Does not become active doc.
+**TLDR:** Fire-and-forget capture to `ideas/` folder. Does not become active doc.
 
-Full procedure: `references/workflows.md` § Notes
+Full procedure: `references/workflows.md` § Ideas
 
 ## Adding Content
 

package/src/skills/brain/commands/brain.md

@@ -1,6 +1,6 @@
 ---
 description: Collaborative scratchpad for planning and research
-argument-hint: "[{topic} | plan|research|review {topic} | note|add {text} | check|done]"
+argument-hint: "[{topic} | plan|research|review {topic} | idea|add {text} | check|done]"
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir:*), Bash(ls:*)
 ---
 
@@ -23,10 +23,10 @@ $ARGUMENTS
 ```
 /brain                      # List recent docs or create new
 /brain {topic}              # SEARCH: Open existing doc (fuzzy match) → active
-/brain plan {topic}         # CREATE: New planning doc → active
-/brain research {topic}     # Create research doc → active
-/brain review {topic}       # Create review doc → active
-/brain note {text}          # Quick capture (fire-and-forget)
+/brain plan {topic}         # CREATE: New planning doc → plans/
+/brain research {topic}     # Create research doc → research/
+/brain review {topic}       # Create review doc → reviews/
+/brain idea {text}          # Quick capture → ideas/ (fire-and-forget)
 /brain add {text}           # Append to active doc
 /brain check                # Address @droid comments in active doc
 /brain done                 # Finalize active doc
@@ -37,7 +37,19 @@ $ARGUMENTS
 **ALWAYS read `~/.droid/skills/brain/overrides.yaml` first.** Use configured values if present, only fall back to defaults if missing.
 
 - `brain_dir` - Where docs live (default varies by AI tool)
-- `inbox_folder` - Subfolder for new docs (empty = flat)
+- `inbox_folder` - Root for type folders (e.g., `0-Inbox`)
+
+## Folder Structure
+
+Docs are organized by type:
+
+```
+{brain_dir}/{inbox_folder}/
+├── plans/
+├── research/
+├── reviews/
+└── ideas/
+```
 
 ## Behavior
 
@@ -45,7 +57,7 @@ Refer to the brain skill for:
 
 - **Opening**: How to fuzzy-match, handle multiple matches, set active
 - **Creating**: Template structure by preset, naming conventions
-- **Notes**: Quick capture workflow
+- **Ideas**: Quick capture workflow
 - **Adding**: Append to active doc with timestamp
 - **Checking**: Find and address @droid comments
 - **Finalizing**: Update status, suggest next steps

package/src/skills/brain/commands/scratchpad.md

@@ -1,6 +1,6 @@
 ---
 description: Collaborative scratchpad for planning and research
-argument-hint: "[{topic} | plan|research|review {topic} | note|add {text} | check|done]"
+argument-hint: "[{topic} | plan|research|review {topic} | idea|add {text} | check|done]"
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir:*), Bash(ls:*)
 ---
 
@@ -23,10 +23,10 @@ $ARGUMENTS
 ```
 /scratchpad                      # List recent docs or create new
 /scratchpad {topic}              # SEARCH: Open existing doc (fuzzy match) → active
-/scratchpad plan {topic}         # CREATE: New planning doc → active
-/scratchpad research {topic}     # Create research doc → active
-/scratchpad review {topic}       # Create review doc → active
-/scratchpad note {text}          # Quick capture (fire-and-forget)
+/scratchpad plan {topic}         # CREATE: New planning doc → plans/
+/scratchpad research {topic}     # Create research doc → research/
+/scratchpad review {topic}       # Create review doc → reviews/
+/scratchpad idea {text}          # Quick capture → ideas/ (fire-and-forget)
 /scratchpad add {text}           # Append to active doc
 /scratchpad check                # Address @droid comments in active doc
 /scratchpad done                 # Finalize active doc
@@ -37,7 +37,19 @@ $ARGUMENTS
 **ALWAYS read `~/.droid/skills/brain/overrides.yaml` first.** Use configured values if present, only fall back to defaults if missing.
 
 - `brain_dir` - Where docs live (default varies by AI tool)
-- `inbox_folder` - Subfolder for new docs (empty = flat)
+- `inbox_folder` - Root for type folders (e.g., `0-Inbox`)
+
+## Folder Structure
+
+Docs are organized by type:
+
+```
+{brain_dir}/{inbox_folder}/
+├── plans/
+├── research/
+├── reviews/
+└── ideas/
+```
 
 ## Behavior
 
@@ -45,7 +57,7 @@ Refer to the brain skill for:
 
 - **Opening**: How to fuzzy-match, handle multiple matches, set active
 - **Creating**: Template structure by preset, naming conventions
-- **Notes**: Quick capture workflow
+- **Ideas**: Quick capture workflow
 - **Adding**: Append to active doc with timestamp
 - **Checking**: Find and address @droid comments
 - **Finalizing**: Update status, suggest next steps

package/src/skills/brain/references/naming.md

@@ -4,17 +4,12 @@ Conventions for naming brain docs.
 
 ## Format
 
+Since docs are organized into type folders (`plans/`, `research/`, `reviews/`, `ideas/`), filenames no longer need a type prefix:
+
 ```
-{type}-{topic-slug}.md
+{topic-slug}.md
 ```
 
-## Components
-
-| Component      | Description                          | Examples                              |
-| -------------- | ------------------------------------ | ------------------------------------- |
-| `{type}`       | Doc type: `plan`, `research`, `note` | `plan`, `research`, `note`            |
-| `{topic-slug}` | Lowercase, hyphen-separated topic    | `auth-refactor`, `caching-strategies` |
-
 ## Slug Rules
 
 1. **Lowercase** all words
@@ -25,26 +20,26 @@ Conventions for naming brain docs.
 
 ## Examples
 
-| Input                                        | Filename                                  |
-| -------------------------------------------- | ----------------------------------------- |
-| `/brain plan Auth Refactor`                  | `plan-auth-refactor.md`                   |
-| `/brain research Caching Strategies`         | `research-caching-strategies.md`          |
-| `/brain plan Transaction Template Rendering` | `plan-transaction-template-rendering.md`  |
-| `/brain note Remember to check rate limits`  | `note-20250115-remember-to-check-rate.md` |
+| Input                                        | Path                                             |
+| -------------------------------------------- | ------------------------------------------------ |
+| `/brain plan Auth Refactor`                  | `plans/auth-refactor.md`                         |
+| `/brain research Caching Strategies`         | `research/caching-strategies.md`                 |
+| `/brain review PR 4530`                      | `reviews/pr-4530.md`                             |
+| `/brain idea Remember to check rate limits`  | `ideas/20250115-remember-to-check-rate.md`       |
 
-## Notes
+## Ideas (Quick Captures)
 
-For notes, include the date in the filename:
+For ideas, include the date in the filename to prevent collisions:
 
 ```
-note-{YYYYMMDD}-{slug}.md
+{YYYYMMDD}-{slug}.md
 ```
 
-This prevents collisions and allows chronological sorting.
+This allows chronological sorting within the `ideas/` folder.
 
 ## Uniqueness
 
 If a file with the generated name already exists:
 
 1. Check if user wants to open existing doc
-2. Or append a numeric suffix: `plan-auth-refactor-2.md`
+2. Or append a numeric suffix: `auth-refactor-2.md`

package/src/skills/brain/references/templates.md

@@ -82,11 +82,12 @@ Suggested changes or actions.
 Overall assessment.
 ```
 
-## Note Template
+## Idea Template
 
 ```markdown
-# Note: {Brief Title}
+# {Brief Title}
 
+**Type:** idea
 **Created:** {date}
 
 {content}

package/src/skills/brain/references/workflows.md

@@ -8,9 +8,11 @@ Detailed procedures for each brain operation.
 
 **Steps:**
 
-1. **Read config first**
-   - Read `~/.droid/skills/brain/overrides.yaml`
-   - Use `brain_dir` if configured, otherwise use default for current AI tool
+1. **Read config first (MANDATORY)**
+   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
+   - If file exists and contains `brain_dir:`, use that path
+   - Only use defaults if the file doesn't exist or `brain_dir` is not set
+   - **Do NOT skip this step or assume defaults**
 
 2. **Search for matches**
 
@@ -35,24 +37,28 @@ Detailed procedures for each brain operation.
 
 ## Creating
 
-**Trigger:** `/brain plan {topic}` or `/brain research {topic}`
+**Trigger:** `/brain plan {topic}`, `/brain research {topic}`, or `/brain review {topic}`
 
 **Steps:**
 
-1. **Read config first**
-   - Read `~/.droid/skills/brain/overrides.yaml`
-   - Use `brain_dir` if configured, otherwise use default for current AI tool
-   - Use `inbox_folder` if configured
+1. **Read config first (MANDATORY)**
+   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
+   - If file exists and contains `brain_dir:`, use that path
+   - Also check for `inbox_folder` setting (e.g., `0-Inbox`)
+   - Only use defaults if the file doesn't exist or `brain_dir` is not set
+   - **Do NOT skip this step or assume defaults**
 
 2. **Generate filename** using naming conventions (see `naming.md`):
-   - Format: `{type}-{topic-slug}.md`
-   - Example: `plan-auth-refactor.md` or `research-caching-strategies.md`
+   - Format: `{topic-slug}.md` (no type prefix - folder indicates type)
+   - Example: `auth-refactor.md` or `caching-strategies.md`
 
-3. **Determine target path:**
-   - If `inbox_folder` is set: `{brain_dir}/{inbox_folder}/{filename}`
-   - Otherwise: `{brain_dir}/{filename}`
+3. **Determine target path based on type:**
+   - Base: `{brain_dir}/{inbox_folder}` (or just `{brain_dir}` if no inbox_folder)
+   - `plan` → `{base}/plans/{filename}`
+   - `research` → `{base}/research/{filename}`
+   - `review` → `{base}/reviews/{filename}`
 
-4. **Create directory** if needed
+4. **Create directory** if needed (type folder may not exist yet)
 
 5. **Apply template** based on preset and type (see `templates.md`)
 
@@ -64,7 +70,7 @@ Detailed procedures for each brain operation.
 7. **Add placeholder comments** for sections needing user input:
    - Read user's mention from `~/.droid/config.yaml` → `user_mention`
    - Use `> @{user_mention}` for placeholders (e.g., `> @fry - Please provide requirements`)
-   - Do NOT use `> @droid` - that's for user-to-AI comments
+   - **CRITICAL:** NEVER use `@droid` - that's for user-to-AI comments, not AI-to-user
 
 8. **Write the doc** with template structure and initial context
 
@@ -72,33 +78,35 @@ Detailed procedures for each brain operation.
 
 10. **Confirm creation** and summarize what was captured
 
-## Notes
+## Ideas
 
-**Trigger:** `/brain note {text}`
+**Trigger:** `/brain idea {text}`
 
 **Steps:**
 
-1. **Read config first**
-   - Read `~/.droid/skills/brain/overrides.yaml`
-   - Use `brain_dir` if configured, otherwise use default for current AI tool
-   - Use `inbox_folder` if configured
+1. **Read config first (MANDATORY)**
+   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
+   - If file exists and contains `brain_dir:`, use that path
+   - Also check for `inbox_folder` setting (e.g., `0-Inbox`)
+   - Only use defaults if the file doesn't exist or `brain_dir` is not set
+   - **Do NOT skip this step or assume defaults**
 
 2. **Generate filename:**
-   - Format: `note-{date}-{slug}.md` where date is `YYYYMMDD`
+   - Format: `{date}-{slug}.md` where date is `YYYYMMDD`
    - Slug from first few words of text
-   - Example: `note-20250115-remember-rate-limits.md`
+   - Example: `20250115-remember-rate-limits.md`
 
 3. **Determine target path:**
-   - If `inbox_folder` is set: `{brain_dir}/{inbox_folder}/{filename}`
-   - Otherwise: `{brain_dir}/{filename}`
+   - Base: `{brain_dir}/{inbox_folder}` (or just `{brain_dir}` if no inbox_folder)
+   - Path: `{base}/ideas/{filename}`
 
-4. **Create simple note:**
+4. **Create simple idea doc:**
    - Markdown preset: Just the text
-   - Obsidian preset: Add frontmatter with `type: note`, `created: {date}`
+   - Obsidian preset: Add frontmatter with `type: idea`, `created: {date}`
 
 5. **Write the file** - Do NOT set as active (fire-and-forget)
 
-6. **Confirm** briefly: "Captured note to {filename}"
+6. **Confirm** briefly: "Captured idea to ideas/{filename}"
 
 ## Adding
 
@@ -140,19 +148,25 @@ Detailed procedures for each brain operation.
 
 2. **Read active doc**
 
-3. **Find all `> @droid` comments**
+3. **Check preserve_comments setting:**
+   - Read `~/.droid/skills/comments/overrides.yaml` if it exists
+   - Look for `preserve_comments` (default: `true`)
+
+4. **Find all `> @droid` comments**
    - Pattern: Lines starting with `> @droid` (blockquote with mention)
 
-4. **For each comment:**
+5. **For each comment:**
    - Show the comment and surrounding context
    - Address the question/request
    - Add response as blockquote with user's mention: `> @{user_mention} Your response here`
    - Example: `> @fry Yes, the index covers that query pattern.`
-   - IMPORTANT: Always include the `>` prefix to maintain blockquote formatting
+   - **CRITICAL:** NEVER use `@droid` in your responses. Use `@{user_mention}` from config (e.g., `@fry`)
+   - **CRITICAL:** Always include the `>` prefix to maintain blockquote formatting
+   - **CRITICAL:** If `preserve_comments: true`, keep the original `@droid` comment and add your response below it. Do NOT remove the original comment.
 
-5. **Update the doc** with responses
+6. **Update the doc** with responses
 
-6. **Summarize** what was addressed
+7. **Summarize** what was addressed
 
 ## Finalizing
 
@@ -185,9 +199,11 @@ Detailed procedures for each brain operation.
 
 **Steps:**
 
-1. **Read config first**
-   - Read `~/.droid/skills/brain/overrides.yaml`
-   - Use `brain_dir` if configured, otherwise use default for current AI tool
+1. **Read config first (MANDATORY)**
+   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
+   - If file exists and contains `brain_dir:`, use that path
+   - Only use defaults if the file doesn't exist or `brain_dir` is not set
+   - **Do NOT skip this step or assume defaults**
 
 2. **Find recent docs:**