github-portfolio-analyzer 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -4,7 +4,25 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.4.0] — 2026-04-03
+
+### Added
+- Smoke tests for `--version` and `--help`
+- Analyze command integration coverage for env-token execution and generated inventory fields
+- `dormant` state in report summaries and documentation, while preserving manual `abandoned` compatibility
+
+### Changed
+- Automatic inactivity classification now returns `dormant` instead of `abandoned`
+- Repository taxonomy inference now prioritizes `experiment` before `library`, broadens `learning` signals, and classifies simple apps like clocks/calculators/games as `product`
+- Fork fallback classification now uses recent fork activity when upstream compare metadata is unavailable
+
+## [1.3.0] — 2026-04-03
+
 ### Added
+- `forkType` classification for forks via the GitHub compare API, distinguishing `active` forks from `passive` clones
+- `publicAlias` best-effort generation for private repositories with OpenAI → Gemini → Anthropic fallback
+- Global CLI credential flags: `--github-token`, `--github-username`, `--openai-key`, `--gemini-key`, `--anthropic-key`
+- Interactive prompting for missing GitHub and optional LLM keys when `analyze` runs on a TTY
 - Colored terminal output — progress, success, warning, and error states with ANSI colors
 - Terminal header with ASCII art, version info, user, token status, and policy status
 - Per-repository progress logging during `analyze` (Analyzing N/total: repo-name)

package/README.md

@@ -495,7 +495,8 @@ Each `portfolio.json.items[]` entry includes:
 
 - `type`: `repo | idea`
 - `category`: `product | tooling | library | learning | content | infra | experiment | template`
-- `state`: `idea | active | stale | abandoned | archived | reference-only`
+- `state`: `idea | active | stale | dormant | abandoned | archived | reference-only`
+- Auto-classified repository inactivity uses `dormant`; `abandoned` remains supported for manual curation.
 - `strategy`: `strategic-core | strategic-support | opportunistic | maintenance | parked`
 - `effort`: `xs | s | m | l | xl`
 - `value`: `low | medium | high | very-high`
@@ -521,11 +522,11 @@ Every repository passes through a deterministic scoring pipeline:
 flowchart LR
     subgraph top [ ]
         direction LR
-        A([repo metadata]) --> B(inferRepoCategory) --> C([category]) --> D(scoreRepository) --> E([score 0–100])
+        A([repo metadata]) --> B(inferRepoCategory) --> C([category]) --> D(scoreRepository) --> E([score 0-100])
     end
     subgraph mid [ ]
         direction RL
-        J(computePriorityBand) <-- I([effort xs–xl]) <-- H(computeEffortEstimate) <-- G([CL 0–5]) <-- F(computeCompletionLevel)
+        J(computePriorityBand) <-- I([effort xs-xl]) <-- H(computeEffortEstimate) <-- G([CL 0-5]) <-- F(computeCompletionLevel)
     end
     E --> F
     E -. feeds .-> J
@@ -606,7 +607,7 @@ final `priorityScore`, which determines the band.
 |---|---|---|
 | State boost | `active` | +10 |
 | State boost | `stale` | +5 |
-| State penalty | `abandoned` or `archived` | −20 |
+| State penalty | `dormant`, `abandoned`, or `archived` | −20 |
 | Quick-win boost | CL 1, 2, or 3 | +10 |
 | Effort penalty | `l` or `xl` | −10 |
 
@@ -614,7 +615,7 @@ final `priorityScore`, which determines the band.
 
 | Band | Range | Meaning |
 |---|---|---|
-| `park` | < 45 | Needs a decision before any investment. Abandoned, low signal, or intentionally paused. |
+| `park` | < 45 | Needs a decision before any investment. Dormant, low signal, or intentionally paused. |
 | `later` | 45–64 | Viable but not urgent. Can return when backlog has room. |
 | `next` | 65–79 | Strong candidate. High score but large effort, or active with average score. |
 | `now` | ≥ 80 | High confidence. Active project, good score, low effort — or manually pinned. |
@@ -633,7 +634,7 @@ updated 200d ago +0  (> 180 days)
 ──────────────────────────────────
 score            25
 
-state=abandoned  −20
+state=dormant    −20
 effort=xl        −10
 ──────────────────────────────────
 priorityScore    −5  → park

package/analyzer.manifest.json

@@ -1,11 +1,21 @@
 {
   "name": "github-portfolio-analyzer",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "commands": [
     { "id": "analyze" },
     { "id": "ingest-ideas" },
     { "id": "build-portfolio" },
-    { "id": "report", "flags": ["--policy", "--explain", "--output", "--format", "--quiet"] }
+    {
+      "id": "report",
+      "flags": [
+        "--policy",
+        "--explain",
+        "--output",
+        "--format",
+        "--quiet",
+        "--presentation-overrides"
+      ]
+    }
   ],
   "outputs": [
     "output/inventory.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-portfolio-analyzer",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "CLI tool to analyze GitHub repos and portfolio ideas",
   "type": "module",
   "bin": {

package/schemas/portfolio-report.schema.json

@@ -51,10 +51,11 @@
         "byState": {
           "type": "object",
           "additionalProperties": true,
-          "required": ["active", "stale", "abandoned", "archived", "idea", "reference-only"],
+          "required": ["active", "stale", "dormant", "abandoned", "archived", "idea", "reference-only"],
           "properties": {
             "active": { "type": "number" },
             "stale": { "type": "number" },
+            "dormant": { "type": "number" },
             "abandoned": { "type": "number" },
             "archived": { "type": "number" },
             "idea": { "type": "number" },
@@ -252,6 +253,13 @@
           "type": "string",
           "enum": ["product", "tooling", "library", "learning", "content", "infra", "experiment", "template"]
         },
+        "fork": { "type": "boolean" },
+        "forkType": {
+          "type": "string",
+          "enum": ["active", "passive"]
+        },
+        "private": { "type": "boolean" },
+        "publicAlias": { "type": "string" },
         "presentationState": {
           "type": "string",
           "enum": ["featured", "complete", "in-progress", "salvageable", "learning", "archived", "hidden"]

package/src/cli.js

@@ -6,23 +6,34 @@ import { parseArgs } from './utils/args.js';
 import packageJson from '../package.json' with { type: 'json' };
 import { UsageError } from './errors.js';
 
-const GLOBAL_OPTIONS = new Set(['help', 'strict', 'version']);
+const GLOBAL_OPTIONS = new Set([
+  'help',
+  'strict',
+  'version',
+  'github-token',
+  'github-username',
+  'openai-key',
+  'gemini-key',
+  'anthropic-key'
+]);
 const COMMAND_OPTIONS = {
   analyze: new Set(['as-of', 'output-dir']),
   'ingest-ideas': new Set(['input', 'prompt', 'output-dir']),
   'build-portfolio': new Set(['output-dir']),
-  report: new Set(['output-dir', 'output', 'format', 'policy', 'priorities', 'explain', 'quiet'])
+  report: new Set(['output-dir', 'output', 'format', 'policy', 'priorities', 'explain', 'quiet', 'presentation-overrides'])
 };
 
 export async function runCli(argv) {
-  const { positional, options } = parseArgs(argv);
+  const { positional, options: rawOptions } = parseArgs(argv);
   const [command] = positional;
-  const strictMode = options.strict === true || options.strict === 'true';
+  const strictMode = rawOptions.strict === true || rawOptions.strict === 'true';
 
   if (strictMode) {
-    validateStrictOptions(command, options);
+    validateStrictOptions(command, rawOptions);
   }
 
+  const options = mapCredentialOptions(rawOptions);
+
   if ((options.version === true && !command) || (command === '-v' && positional.length === 1)) {
     console.log(packageJson.version);
     return;
@@ -58,6 +69,11 @@ function printHelp() {
   console.log('github-portfolio-analyzer');
   console.log('Usage: github-portfolio-analyzer <command> [options]');
   console.log('  --strict               Global: fail on unknown flags (exit code 2)');
+  console.log('  --github-token TOKEN   Global: override GITHUB_TOKEN');
+  console.log('  --github-username USER Global: override GITHUB_USERNAME');
+  console.log('  --openai-key KEY       Global: override OPENAI_API_KEY');
+  console.log('  --gemini-key KEY       Global: override GEMINI_API_KEY');
+  console.log('  --anthropic-key KEY    Global: override ANTHROPIC_API_KEY');
   console.log('Commands:');
   console.log('  analyze          Analyze GitHub repositories and build inventory outputs');
   console.log('  ingest-ideas     Add or update manual project ideas');
@@ -81,6 +97,8 @@ function printHelp() {
   console.log('  --format VALUE         ascii|md|json|all (default: all)');
   console.log('  --policy PATH          Optional policy overlay JSON file');
   console.log('  --priorities PATH      Alias for --policy');
+  console.log('  --presentation-overrides PATH');
+  console.log('                         Optional presentation overrides JSON file');
   console.log('  --explain              Print NOW ranking explainability to console');
   console.log('  --quiet                Suppress non-error logs');
 }
@@ -101,3 +119,14 @@ function validateStrictOptions(command, options) {
     throw new UsageError(`Unknown option(s): ${unknownFlags}`);
   }
 }
+
+function mapCredentialOptions(options) {
+  return {
+    ...options,
+    ...(options['github-token'] !== undefined ? { githubToken: options['github-token'] } : {}),
+    ...(options['github-username'] !== undefined ? { githubUsername: options['github-username'] } : {}),
+    ...(options['openai-key'] !== undefined ? { openaiKey: options['openai-key'] } : {}),
+    ...(options['gemini-key'] !== undefined ? { geminiKey: options['gemini-key'] } : {}),
+    ...(options['anthropic-key'] !== undefined ? { anthropicKey: options['anthropic-key'] } : {})
+  };
+}

package/src/commands/analyze.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { getEnv, requireGithubToken } from '../config.js';
+import { promptMissingKeys, requireGithubToken } from '../config.js';
 import { GithubClient } from '../github/client.js';
 import { fetchAllRepositories, normalizeRepository } from '../github/repos.js';
 import { inspectRepositoryStructure } from '../github/repo-inspection.js';
@@ -15,27 +15,27 @@ import { progress, success, error, warn, fatal } from '../utils/output.js';
 
 export async function runAnalyzeCommand(options = {}) {
   const startTime = Date.now();
-  const env = getEnv();
+  let args = { ...options };
+
+  args = await promptMissingKeys(args, {
+    quiet: args.quiet,
+    required: [
+      { key: 'githubToken', label: 'GitHub Personal Access Token' }
+    ],
+    optional: []
+  });
 
   let token;
   try {
-    token = requireGithubToken(env);
+    token = requireGithubToken(args);
   } catch (err) {
-    fatal('GITHUB_TOKEN missing — set it in .env: GITHUB_TOKEN=your_token');
+    fatal('GITHUB_TOKEN missing — set it in .env or pass --github-token');
     throw err;
   }
 
   const github = new GithubClient(token);
-  const asOfDate = resolveAsOfDate(typeof options['as-of'] === 'string' ? options['as-of'] : undefined);
-  const outputDir = typeof options['output-dir'] === 'string' ? options['output-dir'] : 'output';
-
-  printHeader({
-    command: 'analyze',
-    asOfDate,
-    outputDir,
-    hasToken: Boolean(token),
-    hasPolicy: false,
-  });
+  const asOfDate = resolveAsOfDate(typeof args['as-of'] === 'string' ? args['as-of'] : undefined);
+  const outputDir = typeof args['output-dir'] === 'string' ? args['output-dir'] : 'output';
 
   let user;
   try {
@@ -49,9 +49,18 @@ export async function runAnalyzeCommand(options = {}) {
     throw err;
   }
 
+  printHeader({
+    command: 'analyze',
+    asOfDate,
+    outputDir,
+    hasToken: Boolean(token),
+    hasPolicy: false,
+    username: args.githubUsername || user.login
+  });
+
   let repositories;
   try {
-    repositories = await fetchAllRepositories(github);
+    repositories = await fetchAllRepositories(github, asOfDate);
   } catch (err) {
     if (err && (err.status === 401 || err.status === 403)) {
       fatal('GitHub authentication failed — check your GITHUB_TOKEN permissions');

package/src/commands/report.js

@@ -1,6 +1,8 @@
 import path from 'node:path';
 import { buildReportModel } from '../core/report.js';
+import { createPublicAliasLLMCaller, generatePublicAlias } from '../core/publicAliasGenerator.js';
 import { loadPresentationOverrides, applyPresentationOverrides } from '../core/presentationOverrides.js';
+import { getEnv } from '../config.js';
 import { readJsonFile, readJsonFileIfExists } from '../io/files.js';
 import { writeReportAscii, writeReportJson, writeReportMarkdown } from '../io/report.js';
 import { UsageError } from '../errors.js';
@@ -46,11 +48,38 @@ export async function runReportCommand(options = {}) {
   const presentationOverridesPath = resolvePresentationOverridesPath(options);
   const presentationOverrides = await loadPresentationOverrides(presentationOverridesPath);
   const reportModel = buildReportModel(portfolio, inventory, { policyOverlay });
+  const portfolioDescriptionBySlug = new Map(
+    (Array.isArray(portfolio?.items) ? portfolio.items : []).map((item) => [
+      String(item?.slug ?? '').trim(),
+      item?.description ?? ''
+    ])
+  );
+  const callLLM = createPublicAliasLLMCaller(getEnv(options));
 
   if (presentationOverrides.size > 0) {
     reportModel.items = applyPresentationOverrides(reportModel.items, presentationOverrides);
   }
 
+  if (typeof callLLM === 'function') {
+    const privateItems = reportModel.items.filter((item) => item.private && !item.publicAlias);
+    const aliasBySlug = new Map();
+
+    for (const item of privateItems) {
+      const itemForAlias = {
+        ...item,
+        description: portfolioDescriptionBySlug.get(String(item.slug ?? '').trim()) ?? ''
+      };
+      item.publicAlias = await generatePublicAlias(itemForAlias, callLLM);
+      if (item.publicAlias) {
+        aliasBySlug.set(item.slug, item.publicAlias);
+      }
+    }
+
+    if (aliasBySlug.size > 0) {
+      applyAliasesToReportModel(reportModel, aliasBySlug);
+    }
+  }
+
   const writtenPaths = [];
 
   if (formatOption === 'json' || formatOption === 'all') {
@@ -127,6 +156,27 @@ function validatePolicyOverlay(policy, policyPath) {
   }
 }
 
+function applyAliasesToReportModel(reportModel, aliasBySlug) {
+  for (const item of reportModel.items) {
+    if (!item.private || !item.publicAlias) {
+      continue;
+    }
+
+    item.slug = item.publicAlias;
+    item.title = item.publicAlias;
+  }
+
+  const sections = ['top10ByScore', 'now', 'next', 'later', 'park'];
+  for (const section of sections) {
+    for (const item of reportModel.summary[section] ?? []) {
+      const alias = aliasBySlug.get(item.slug);
+      if (alias) {
+        item.slug = alias;
+      }
+    }
+  }
+}
+
 function printNowExplain(reportModel) {
   const nowItems = Array.isArray(reportModel?.items)
     ? reportModel.items.filter((item) => item.priorityBand === 'now')
@@ -185,7 +235,7 @@ function computeStateAdjustment(state) {
     return 5;
   }
 
-  if (state === 'abandoned' || state === 'archived') {
+  if (state === 'dormant' || state === 'abandoned' || state === 'archived') {
     return -20;
   }
 

package/src/config.js

@@ -1,18 +1,105 @@
 import dotenv from 'dotenv';
+import { createInterface } from 'node:readline';
 
 dotenv.config({ quiet: true });
 
-export function getEnv() {
+/**
+ * Returns env vars with optional CLI overrides.
+ * args uses camelCase keys, for example { githubToken: '...' }.
+ */
+export function getEnv(args = {}) {
   return {
-    githubToken: process.env.GITHUB_TOKEN ?? '',
-    githubUsername: process.env.GITHUB_USERNAME ?? ''
+    githubToken: args.githubToken ?? process.env.GITHUB_TOKEN ?? '',
+    githubUsername: args.githubUsername ?? process.env.GITHUB_USERNAME ?? '',
+    openaiKey: args.openaiKey ?? process.env.OPENAI_API_KEY ?? '',
+    geminiKey: args.geminiKey ?? process.env.GEMINI_API_KEY ?? '',
+    anthropicKey: args.anthropicKey ?? process.env.ANTHROPIC_API_KEY ?? ''
   };
 }
 
-export function requireGithubToken(env = getEnv()) {
+export function requireGithubToken(args = {}) {
+  const env = getEnv(args);
+
   if (!env.githubToken) {
-    throw new Error('Missing GITHUB_TOKEN. Add it to your .env file before running analyze.');
+    throw new Error(
+      'Missing GITHUB_TOKEN. Add it to your .env file or pass --github-token <token>'
+    );
   }
 
   return env.githubToken;
 }
+
+/**
+ * Interactive terminal prompt for missing keys.
+ * Only runs on TTY and when quiet !== true.
+ */
+export async function promptMissingKeys(
+  args = {},
+  { required = [], optional = [], quiet = false, input = process.stdin, output = process.stderr } = {}
+) {
+  if (quiet || !input?.isTTY) {
+    return args;
+  }
+
+  const env = getEnv(args);
+  const result = { ...args };
+  const rl = createInterface({ input, output });
+  rl.stdoutMuted = false;
+
+  const askVisible = (label, hint) =>
+    new Promise((resolve) => {
+      rl.question(`  ${label}${hint ? ` (${hint})` : ''}: `, resolve);
+    });
+
+  const askSilent = (label, hint) =>
+    new Promise((resolve) => {
+      const originalWriteToOutput = rl._writeToOutput;
+      const hintText = hint ? ` (${hint})` : '';
+      rl.output.write(`  ${label}${hintText}: `);
+      rl.stdoutMuted = true;
+      rl._writeToOutput = (str) => {
+        if (rl.stdoutMuted) {
+          rl.output.write('');
+          return;
+        }
+
+        rl.output.write(str);
+      };
+
+      rl.question('', (value) => {
+        rl.stdoutMuted = false;
+        rl._writeToOutput = originalWriteToOutput;
+        rl.output.write('\n');
+        resolve(value);
+      });
+    });
+
+  for (const { key, label } of required) {
+    if (env[key]) {
+      continue;
+    }
+
+    const value = await askSilent(label, 'required');
+    if (!value.trim()) {
+      rl.close();
+      throw new Error(`${label} is required.`);
+    }
+
+    result[key] = value.trim();
+  }
+
+  for (const { key, label } of optional) {
+    if (env[key]) {
+      continue;
+    }
+
+    const prompt = key === 'githubUsername' ? askVisible : askSilent;
+    const value = await prompt(label, 'optional, Enter to skip');
+    if (value.trim()) {
+      result[key] = value.trim();
+    }
+  }
+
+  rl.close();
+  return result;
+}

package/src/core/classification.js

@@ -11,7 +11,7 @@ export function classifyActivity(pushedAt, asOfDate) {
     return 'stale';
   }
 
-  return 'abandoned';
+  return 'dormant';
 }
 
 export function classifyMaturity(sizeKb) {

package/src/core/publicAliasGenerator.js

@@ -0,0 +1,202 @@
+const OPENAI_URL = 'https://api.openai.com/v1/responses';
+const GEMINI_URL =
+  'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent';
+const ANTHROPIC_URL = 'https://api.anthropic.com/v1/messages';
+
+/**
+ * Generates a plausible, non-identifying alias for private repositories.
+ * Preserves manually curated aliases when present.
+ */
+export async function generatePublicAlias(item, callLLM) {
+  if (!item?.private) {
+    return null;
+  }
+
+  if (item.publicAlias) {
+    return item.publicAlias;
+  }
+
+  if (typeof callLLM !== 'function') {
+    return null;
+  }
+
+  const prompt = [
+    'Given a private software project with:',
+    `- category: ${item.category ?? 'unknown'}`,
+    `- language: ${item.language ?? 'unknown'}`,
+    `- topics: ${Array.isArray(item.topics) ? item.topics.join(', ') : 'none'}`,
+    `- description: "${String(item.description ?? '').substring(0, 200)}"`,
+    '',
+    'Generate a plausible but fictional project slug (2-3 words, kebab-case).',
+    'Must reflect the technical domain. Must NOT contain: original repo name,',
+    'company names, client names, person names, or any identifying information.',
+    'Return ONLY the slug, nothing else. Example: "relay-task-engine"'
+  ].join('\n');
+
+  try {
+    const raw = await callLLM(prompt);
+    return (
+      raw
+        ?.trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '') || null
+    );
+  } catch {
+    return null;
+  }
+}
+
+export function createPublicAliasLLMCaller(env = {}) {
+  const providers = [];
+
+  if (env.openaiKey) {
+    providers.push((prompt) => callOpenAI(env.openaiKey, prompt));
+  }
+
+  if (env.geminiKey) {
+    providers.push((prompt) => callGemini(env.geminiKey, prompt));
+  }
+
+  if (env.anthropicKey) {
+    providers.push((prompt) => callAnthropic(env.anthropicKey, prompt));
+  }
+
+  if (providers.length === 0) {
+    return null;
+  }
+
+  return async function callLLM(prompt) {
+    let lastError = null;
+
+    for (const provider of providers) {
+      try {
+        const value = await provider(prompt);
+        if (typeof value === 'string' && value.trim()) {
+          return value;
+        }
+      } catch (error) {
+        lastError = error;
+      }
+    }
+
+    if (lastError) {
+      throw lastError;
+    }
+
+    return null;
+  };
+}
+
+async function callOpenAI(apiKey, prompt) {
+  const data = await postJson(
+    OPENAI_URL,
+    {
+      model: 'gpt-4.1-mini',
+      input: prompt,
+      max_output_tokens: 40
+    },
+    {
+      Authorization: `Bearer ${apiKey}`
+    }
+  );
+
+  return extractOpenAIText(data);
+}
+
+async function callGemini(apiKey, prompt) {
+  const data = await postJson(
+    `${GEMINI_URL}?key=${encodeURIComponent(apiKey)}`,
+    {
+      contents: [
+        {
+          role: 'user',
+          parts: [{ text: prompt }]
+        }
+      ],
+      generationConfig: {
+        temperature: 0.2,
+        maxOutputTokens: 40
+      }
+    }
+  );
+
+  return data?.candidates?.[0]?.content?.parts
+    ?.map((part) => part?.text ?? '')
+    .join('')
+    .trim();
+}
+
+async function callAnthropic(apiKey, prompt) {
+  const data = await postJson(
+    ANTHROPIC_URL,
+    {
+      model: 'claude-3-5-haiku-latest',
+      max_tokens: 40,
+      messages: [
+        {
+          role: 'user',
+          content: prompt
+        }
+      ]
+    },
+    {
+      'x-api-key': apiKey,
+      'anthropic-version': '2023-06-01'
+    }
+  );
+
+  return data?.content
+    ?.map((part) => (part?.type === 'text' ? part.text : ''))
+    .join('')
+    .trim();
+}
+
+async function postJson(url, body, headers = {}) {
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...headers
+    },
+    body: JSON.stringify(body)
+  });
+
+  const data = await safeJson(response);
+  if (!response.ok) {
+    const details = data?.error?.message ?? data?.message ?? response.statusText;
+    throw new Error(`LLM request failed: ${response.status} ${details}`.trim());
+  }
+
+  return data;
+}
+
+async function safeJson(response) {
+  const contentType = response.headers.get('content-type') ?? '';
+  if (!contentType.includes('application/json')) {
+    return null;
+  }
+
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+function extractOpenAIText(data) {
+  if (typeof data?.output_text === 'string' && data.output_text.trim()) {
+    return data.output_text.trim();
+  }
+
+  for (const output of data?.output ?? []) {
+    for (const content of output?.content ?? []) {
+      if (typeof content?.text === 'string' && content.text.trim()) {
+        return content.text.trim();
+      }
+    }
+  }
+
+  return null;
+}

package/src/core/report.js

@@ -1,6 +1,6 @@
 import { utcNowISOString } from '../utils/time.js';
 
-const STATE_ORDER = ['active', 'stale', 'abandoned', 'archived', 'idea', 'reference-only'];
+const STATE_ORDER = ['active', 'stale', 'dormant', 'abandoned', 'archived', 'idea', 'reference-only'];
 const EFFORT_ORDER = ['xs', 's', 'm', 'l', 'xl'];
 const BAND_STRENGTH = {
   park: 0,
@@ -109,9 +109,9 @@ export function computePriorityBand(input) {
   } else if (state === 'stale') {
     priorityScore += 5;
     reasons.push('State boost: stale (+5)');
-  } else if (state === 'abandoned' || state === 'archived') {
+  } else if (state === 'dormant' || state === 'abandoned' || state === 'archived') {
     priorityScore -= 20;
-    reasons.push('State penalty: abandoned/archived (-20)');
+    reasons.push('State penalty: dormant/abandoned/archived (-20)');
   }
 
   if (completionLevel >= 1 && completionLevel <= 3) {
@@ -142,8 +142,15 @@ export function buildReportModel(portfolioData, inventoryData = null, options =
   const inventoryLookup = buildInventoryLookup(inventoryItems);
 
   const reportItems = portfolioItems.map((item) => {
-    const slug = String(item.slug ?? '').trim();
-    const inventorySignals = inventoryLookup.get(slug) ?? null;
+    const rawSlug = String(item.slug ?? '').trim();
+    const inventorySignals = inventoryLookup.get(rawSlug) ?? null;
+    const isPrivate = Boolean(item.private);
+    const alias = typeof item.publicAlias === 'string' && item.publicAlias.trim()
+      ? item.publicAlias.trim()
+      : null;
+    const slug = isPrivate && alias ? alias : rawSlug;
+    const rawTitle = resolveTitle(item);
+    const title = isPrivate && alias ? alias : rawTitle;
 
     const completionLevel = computeCompletionLevel(item, inventorySignals);
     const effortEstimate = computeEffortEstimate(item, completionLevel, inventorySignals);
@@ -163,9 +170,9 @@ export function buildReportModel(portfolioData, inventoryData = null, options =
     } = applyPolicyOverlayToItem(
       {
         ...item,
-        slug,
+        slug: rawSlug,
         type: resolveItemType(item),
-        title: resolveTitle(item),
+        title: rawTitle,
         tags: collectItemTags(item)
       },
       {
@@ -180,7 +187,7 @@ export function buildReportModel(portfolioData, inventoryData = null, options =
     return {
       slug,
       type: resolveItemType(item),
-      title: resolveTitle(item),
+      title,
       score: Number(item.score ?? 0),
       state: String(item.state ?? 'idea'),
       effort: normalizeEffort(item.effort) ?? 'm',
@@ -199,9 +206,15 @@ export function buildReportModel(portfolioData, inventoryData = null, options =
       // presentation fields — passed directly from portfolio item
       ...(item.language != null ? { language: item.language } : {}),
       ...(Array.isArray(item.topics) && item.topics.length > 0 ? { topics: item.topics } : {}),
-      ...(item.htmlUrl != null ? { htmlUrl: item.htmlUrl } : {}),
-      ...(item.homepage != null ? { homepage: item.homepage } : {}),
-      ...(item.category != null ? { category: item.category } : {})
+      ...(!isPrivate && item.htmlUrl != null ? { htmlUrl: item.htmlUrl } : {}),
+      ...(!isPrivate && item.homepage != null ? { homepage: item.homepage } : {}),
+      ...(item.category != null ? { category: item.category } : {}),
+      ...(item.fork != null ? { fork: Boolean(item.fork) } : {}),
+      ...(item.forkType != null ? { forkType: item.forkType } : {}),
+      ...(item.private != null ? { private: Boolean(item.private) } : {}),
+      ...(item.publicAlias != null ? { publicAlias: item.publicAlias } : {}),
+      ...(!isPrivate && item.description != null ? { description: item.description } : {}),
+      ...(isPrivate && item.description != null ? { _description: item.description } : {})
     };
   });
 
@@ -260,7 +273,12 @@ export function buildReportModel(portfolioData, inventoryData = null, options =
     matrix: {
       completionByEffort: matrix
     },
-    items: sortedByPriority.map(({ priorityScore: _priorityScore, ...item }) => item)
+    items: sortedByPriority.map((item) => {
+      const publicItem = { ...item };
+      delete publicItem.priorityScore;
+      delete publicItem._description;
+      return publicItem;
+    })
   };
 }
 
@@ -291,6 +309,7 @@ function buildByStateSummary(reportItems) {
   const summary = {
     active: 0,
     stale: 0,
+    dormant: 0,
     abandoned: 0,
     archived: 0,
     idea: 0,

package/src/core/taxonomy.js

@@ -6,13 +6,14 @@ function inferRepoCategory(repository) {
   const topics = Array.isArray(repository.topics)
     ? repository.topics.map((topic) => String(topic).toLowerCase())
     : [];
+  const nameAndTopics = [name, ...topics].join(' ');
   const all = [name, desc, ...topics].join(' ');
 
   if (/\b(prompt|note|notes|snippet|snippets|cheatsheet|doc|docs|documentation|knowledge|wiki|resource|resources|writing|content|guide|guides|cookbook)\b/.test(all)) {
     return 'content';
   }
 
-  if (/\b(learn|learning|study|exercise|exercises|course|tutorial|tutorials|practice|training|bootcamp|challenge|challenges|kata)\b/.test(all)) {
+  if (/\b(learn|learning|study|exercise|exercises|course|tutorial|tutorials|practice|training|bootcamp|challenge|challenges|kata|curriculum|syllabus)\b/.test(all)) {
     return 'learning';
   }
 
@@ -20,6 +21,10 @@ function inferRepoCategory(repository) {
     return 'template';
   }
 
+  if (/\b(poc|proof|experiment|spike|prototype|sandbox|playground)\b/.test(nameAndTopics)) {
+    return 'experiment';
+  }
+
   if (/\b(lib|library|sdk|package|npm|module|plugin|extension|addon|util|utils|helper|helpers)\b/.test(all)) {
     return 'library';
   }
@@ -28,11 +33,11 @@ function inferRepoCategory(repository) {
     return 'infra';
   }
 
-  if (/\b(poc|proof|experiment|spike|demo|prototype|sandbox|playground|try|trying)\b/.test(all)) {
+  if (/\b(demo|try|trying)\b/.test(all)) {
     return 'experiment';
   }
 
-  if (/\b(app|application|system|platform|service|api|backend|frontend|web|mobile|dashboard|portal|saas)\b/.test(all)) {
+  if (/\b(app|application|system|platform|service|api|backend|frontend|web|mobile|dashboard|portal|saas|clock|calculator|game|games|viewer|weather|timer|todo|player|tracker)\b/.test(all)) {
     return 'product';
   }
 
@@ -130,6 +135,10 @@ export function mapIdeaStatusToState(status) {
     return 'stale';
   }
 
+  if (value === 'dormant') {
+    return 'dormant';
+  }
+
   if (value === 'abandoned' || value === 'dropped') {
     return 'abandoned';
   }
@@ -154,7 +163,7 @@ function defaultRepoNextAction(state) {
     return formatNextAction('Refresh', 'execution documentation', 'README run steps are validated in a clean environment');
   }
 
-  if (state === 'abandoned') {
+  if (state === 'dormant' || state === 'abandoned') {
     return formatNextAction('Decide', 'retain or archive status', 'README contains a documented decision and rationale');
   }
 
@@ -170,7 +179,7 @@ function normalizeCategory(value) {
 }
 
 function normalizeState(value, fallback) {
-  return normalizeEnum(value, ['idea', 'active', 'stale', 'abandoned', 'archived', 'reference-only']) ?? fallback;
+  return normalizeEnum(value, ['idea', 'active', 'stale', 'dormant', 'abandoned', 'archived', 'reference-only']) ?? fallback;
 }
 
 function normalizeStrategy(value) {

package/src/github/client.js

@@ -15,6 +15,7 @@ export class GithubClient {
   constructor(token) {
     this.token = token;
     this.maxRetries = 4;
+    this._delay = sleepMs;
   }
 
   async request(path, init = {}) {
@@ -42,7 +43,7 @@ export class GithubClient {
           responseHeaders: response.headers,
           attempt
         });
-        await sleepMs(delayMs);
+        await this._delay(delayMs);
         continue;
       }
 

package/src/github/repo-inspection.js

@@ -37,8 +37,12 @@ async function readPackageJson(client, repository) {
   try {
     const response = await client.request(repoApiPath(repository, 'contents/package.json'));
     if (response?.content && response?.encoding === 'base64') {
-      const decoded = Buffer.from(response.content, 'base64').toString('utf8');
-      return JSON.parse(decoded);
+      try {
+        const decoded = Buffer.from(response.content, 'base64').toString('utf8');
+        return JSON.parse(decoded);
+      } catch {
+        return null;
+      }
     }
     return null;
   } catch (error) {

package/src/github/repos.js

@@ -1,6 +1,47 @@
+import { daysSince } from '../core/classification.js';
+
 const PAGE_SIZE = 100;
 
-export async function fetchAllRepositories(client) {
+/**
+ * Classifies a fork as active or passive.
+ * Active forks are either ahead of the upstream default branch or recently active
+ * when upstream comparison metadata is unavailable.
+ */
+export async function classifyFork(client, repo, asOfDate = new Date().toISOString().slice(0, 10)) {
+  if (!repo?.fork) {
+    return null;
+  }
+
+  const parent = repo.parent;
+  const pushedAt = repo._pushedAt ?? repo.pushed_at ?? repo.pushedAt ?? null;
+  const isRecentlyActive = pushedAt ? daysSince(pushedAt, asOfDate) <= 90 : false;
+  const fallbackForkType = isRecentlyActive ? 'active' : 'passive';
+
+  if (!parent) {
+    return fallbackForkType;
+  }
+
+  const ownerLogin = repo.owner?.login ?? repo.ownerLogin;
+  const parentOwner = parent.owner?.login;
+  const parentBranch = parent.default_branch ?? parent.defaultBranch ?? 'main';
+  const branch = repo.default_branch ?? repo.defaultBranch ?? 'main';
+
+  if (!ownerLogin || !parentOwner || !repo.name) {
+    return fallbackForkType;
+  }
+
+  try {
+    const comparison = await client.request(
+      `/repos/${encodeURIComponent(ownerLogin)}/${encodeURIComponent(repo.name)}/compare/${encodeURIComponent(parentOwner)}:${encodeURIComponent(parentBranch)}...${encodeURIComponent(ownerLogin)}:${encodeURIComponent(branch)}`
+    );
+
+    return (comparison?.ahead_by ?? 0) > 0 ? 'active' : 'passive';
+  } catch {
+    return fallbackForkType;
+  }
+}
+
+export async function fetchAllRepositories(client, asOfDate = new Date().toISOString().slice(0, 10)) {
   const repositories = [];
 
   for (let page = 1; ; page += 1) {
@@ -26,6 +67,17 @@ export async function fetchAllRepositories(client) {
   }
 
   repositories.sort((left, right) => left.full_name.localeCompare(right.full_name));
+
+  const forks = repositories.filter((repository) => repository.fork);
+  for (let index = 0; index < forks.length; index += 5) {
+    const batch = forks.slice(index, index + 5);
+    await Promise.all(
+      batch.map(async (repository) => {
+        repository.forkType = await classifyFork(client, repository, asOfDate);
+      })
+    );
+  }
+
   return repositories;
 }
 
@@ -39,6 +91,8 @@ export function normalizeRepository(repo) {
     private: repo.private,
     archived: repo.archived,
     fork: repo.fork,
+    forkType: repo.forkType ?? null,
+    parent: repo.parent ?? null,
     htmlUrl: repo.html_url,
     description: repo.description,
     language: repo.language,

package/src/io/markdown.js

@@ -109,7 +109,7 @@ function renderPortfolioSummary(payload) {
 
   lines.push('');
 
-  for (const state of ['active', 'stale', 'abandoned', 'idea']) {
+  for (const state of ['active', 'stale', 'dormant', 'abandoned', 'idea']) {
     lines.push(`## State: ${state}`);
     lines.push('');
 

package/src/utils/header.js

@@ -13,9 +13,9 @@ ${AMBER}  later█░░░ ↑${RESET}
 ${DIM}            ↓${RESET}
 ${GREEN}  ✓ report.json${RESET}`;
 
-export function printHeader({ command: _command, asOfDate, outputDir, hasToken, hasPolicy, version }) {
+export function printHeader({ command: _command, asOfDate, outputDir, hasToken, hasPolicy, version, username }) {
   const node = process.version;
-  const user = process.env.GITHUB_USERNAME ?? '—';
+  const user = username ?? process.env.GITHUB_USERNAME ?? '—';
   const token = hasToken ? `${GREEN}✓ set${RESET}` : `${AMBER}not set${RESET}`;
   const policy = hasPolicy ? `${GREEN}✓ set${RESET}` : `${GRAY}not set${RESET}`;
   const ver = version ?? packageJson.version;

package/src/utils/time.js

@@ -14,6 +14,9 @@ export function resolveAsOfDate(input) {
     if (Number.isNaN(asDate.getTime())) {
       throw new Error(`Invalid --as-of value: ${input}. Expected YYYY-MM-DD.`);
     }
+    if (asDate.toISOString().slice(0, 10) !== input) {
+      throw new Error(`Invalid --as-of value: ${input}. Date does not exist in the calendar.`);
+    }
 
     return input;
   }