Fix: Standardize outputs/ and improve GitHub token guidance

.agent/skills/work-chronicler-detect-projects/SKILL.md

@@ -57,6 +57,17 @@ Analyze work history to identify major projects and group related work.
    - Consider temporal clustering (work in same 2-4 week period)
    - Use PR labels and repository patterns
 
+## Output Location
+
+**IMPORTANT:** You must do BOTH of the following:
+
+1. **Respond in-thread** with the project summary (for immediate feedback and MCP integration)
+2. **Save to file**: `<profile-root>/outputs/projects-detected-YYYY-MM-DD.md`
+
+Get the profile root with: `work-chronicler workspace root`
+
+This ensures users have both immediate feedback AND a persistent file they can reference later.
+
 ## Project Summary Format
 
 For each project, gather:

.agent/skills/work-chronicler-detect-themes/SKILL.md

@@ -77,6 +77,17 @@ Work data is stored in the workspace work-log directory:
    - PR titles and descriptions keywords
    - Timeline trends (what themes emerged when?)
 
+## Output Location
+
+**IMPORTANT:** You must do BOTH of the following:
+
+1. **Respond in-thread** with the themes analysis (for immediate feedback and MCP integration)
+2. **Save to file**: `<profile-root>/outputs/themes-detected-YYYY-MM-DD.md`
+
+Get the profile root with: `work-chronicler workspace root`
+
+This ensures users have both immediate feedback AND a persistent file they can reference later.
+
 ## Output Format
 
 ```markdown

.agent/skills/work-chronicler-generate-resume-bullets/SKILL.md

@@ -66,7 +66,14 @@ Work data is stored in the workspace work-log directory:
 
 ## Output Location
 
-Save generated documents to `generated/resume-bullets-YYYY-MM-DD.md` in the workspace root.
+**IMPORTANT:** You must do BOTH of the following:
+
+1. **Respond in-thread** with the resume bullets (for immediate feedback and MCP integration)
+2. **Save to file**: `<profile-root>/outputs/resume-bullets-YYYY-MM-DD.md`
+
+Get the profile root with: `work-chronicler workspace root`
+
+This ensures users have both immediate feedback AND a persistent file they can reference later.
 
 ## Bullet Point Format
 

.agent/skills/work-chronicler-summarize-work/SKILL.md

@@ -65,6 +65,17 @@ Generate a summary including:
 - **Timeline**: Busiest periods, activity trends
 - **Notable Contributions**: Largest PRs, most complex changes
 
+## Output Location
+
+**IMPORTANT:** You must do BOTH of the following:
+
+1. **Respond in-thread** with the work summary (for immediate feedback and MCP integration)
+2. **Save to file**: `<profile-root>/outputs/work-summary-YYYY-MM-DD.md`
+
+Get the profile root with: `work-chronicler workspace root`
+
+This ensures users have both immediate feedback AND a persistent file they can reference later.
+
 ## Example Output
 
 ```markdown

.agent/skills/work-chronicler-update-resume/SKILL.md

@@ -104,7 +104,14 @@ Work data is stored in the workspace work-log directory:
 
 ## Output Location
 
-Save generated documents to `generated/resume-updated-YYYY-MM-DD.md` in the workspace root.
+**IMPORTANT:** You must do BOTH of the following:
+
+1. **Respond in-thread** with the resume updates (for immediate feedback and MCP integration)
+2. **Save to file**: `<profile-root>/outputs/resume-updated-YYYY-MM-DD.md`
+
+Get the profile root with: `work-chronicler workspace root`
+
+This ensures users have both immediate feedback AND a persistent file they can reference later.
 
 ## Output Format
 

.agent/skills/work-chronicler-write-self-review/SKILL.md

@@ -75,7 +75,14 @@ Work data is stored in the workspace work-log directory:
 
 ## Output Location
 
-Save generated documents to `generated/self-review-YYYY-MM-DD.md` in the workspace root.
+**IMPORTANT:** You must do BOTH of the following:
+
+1. **Respond in-thread** with the self-review (for immediate feedback and MCP integration)
+2. **Save to file**: `<profile-root>/outputs/self-review-YYYY-MM-DD.md`
+
+Get the profile root with: `work-chronicler workspace root`
+
+This ensures users have both immediate feedback AND a persistent file they can reference later.
 
 ## Output Format
 

.gitignore

@@ -36,7 +36,8 @@ yarn-error.log*
 work-log/
 work-chronicler.yaml
 
-# generated documents (resumes, reviews, etc.)
+# AI-generated documents (resumes, reviews, summaries, etc.)
+# Note: NOT outputs/ because that's used in portable workspace structure
 generated/
 
 # Claude Code MCP configuration (contains API keys)

AGENTS.md

@@ -191,15 +191,20 @@ profiles/manager/
     └── team-timeline.json
 ```
 
-AI-generated documents are saved to `generated/` (gitignored):
+AI-generated documents are saved to `outputs/`:
 
 ```
-generated/
+outputs/
 ├── resume-updated-YYYY-MM-DD.md
 ├── resume-bullets-YYYY-MM-DD.md
-└── self-review-YYYY-MM-DD.md
+├── self-review-YYYY-MM-DD.md
+├── work-summary-YYYY-MM-DD.md
+├── projects-detected-YYYY-MM-DD.md
+└── themes-detected-YYYY-MM-DD.md
 ```
 
+Note: Manager mode uses `reports/<id>/outputs/` for per-report generated documents.
+
 ## Dependencies
 
 Key dependencies:

README.md

@@ -275,7 +275,15 @@ See [work-chronicler.example.yaml](work-chronicler.example.yaml) for a complete
 
 ### GitHub Token
 
-Create a personal access token at https://github.com/settings/tokens with the `repo` scope (or `public_repo` for public repos only).
+Create a personal access token at https://github.com/settings/tokens with the following scopes:
+
+**Required:**
+- `repo` (for private repos) or `public_repo` (for public repos only)
+
+**Required for auto-discovery with organizations:**
+- `read:org` - Needed to query organization repositories during `init` auto-discovery
+
+Without `read:org`, you can still use work-chronicler by entering repos manually during setup.
 
 ### JIRA Token
 

src/cli/commands/init/index.ts

@@ -742,7 +742,9 @@ async function promptGitHubTokenForManager(): Promise<string> {
   console.log(
     chalk.dim('\nCreate a token at: https://github.com/settings/tokens'),
   );
-  console.log(chalk.dim('Required scopes: repo or public_repo\n'));
+  console.log(
+    chalk.dim('Required scopes: repo or public_repo, read:org for orgs\n'),
+  );
 
   return await password({
     message: 'GitHub token:',

src/cli/commands/init/init.prompts.ts

@@ -219,7 +219,7 @@ export async function promptRepoDiscoveryMethod(
         name: 'Auto-discover',
         value: 'auto',
         description:
-          'Find repos where you have PRs (slow for large orgs, may miss old contributions)',
+          'Find repos where you have PRs (requires read:org scope for orgs, slow for large orgs)',
       },
       {
         name: 'All repos (slowest)',
@@ -434,7 +434,11 @@ export async function promptTokensReady(
 
   if (sources.includes('github')) {
     console.log(chalk.dim('  GitHub: https://github.com/settings/tokens'));
-    console.log(chalk.dim('          (Required scopes: repo or public_repo)'));
+    console.log(
+      chalk.dim(
+        '          (Required scopes: repo or public_repo, read:org for orgs)',
+      ),
+    );
   }
 
   if (sources.includes('jira')) {

src/cli/commands/init/init.utils.ts

@@ -282,7 +282,18 @@ async function checkIfOrganization(
       login,
     });
     return response.organization !== null;
-  } catch {
+  } catch (error) {
+    // Check if this is an INSUFFICIENT_SCOPES error for read:org
+    if (error && typeof error === 'object' && 'errors' in error) {
+      const errors = (error as { errors?: Array<{ type?: string }> }).errors;
+      if (errors?.some((e) => e.type === 'INSUFFICIENT_SCOPES')) {
+        throw new Error(
+          `GitHub token is missing the 'read:org' scope, which is required to query organizations.\n` +
+            `Please add this scope at: https://github.com/settings/tokens`,
+        );
+      }
+    }
+    // For other errors, assume it's a user (not an org)
     return false;
   }
 }