github-portfolio-analyzer 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -4,7 +4,13 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [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)
@@ -12,6 +18,19 @@ All notable changes to this project will be documented in this file.
 - Fallback count in analyze summary when structural inspection fails
 - Fatal error messages for missing token, auth failure, and rate limit
 
+## [1.2.0] — 2026-04-02
+
+### Added
+- `inferRepoCategory()` em `taxonomy.js`: inferência de categoria por heurística de nome, descrição e topics — detecta content, learning, template, library, infra, experiment, product; fallback: tooling
+- `CATEGORY_WEIGHTS` em `scoring.js`: pesos de scoring distintos por categoria — `hasLicense` e `hasTests` zerados para content/learning/experiment, baselines altos para experiment (45), learning (35), template (30) e content (25)
+- `category` exposto no output de `buildReportModel` em `report.js` — consumers do report (worker, frontend) agora recebem essa informação
+- `docs/SCORING_MODEL.md`: documentação completa com tabela de pesos, exemplos end-to-end por categoria, e seção para agentes/LLMs
+- Seção de scoring v2 no `AGENT_GUIDE.md`
+
+### Changed
+- `scoreRepository` agora lê `repository.category` para selecionar os pesos corretos; fallback para `tooling` se category ausente ou inválida
+- `sources.category` em `buildRepoTaxonomy` retorna `'inferred'` em vez de `'default'`
+
 ## [1.0.0] — 2026-03-31
 
 ### Added

package/README.md

@@ -98,14 +98,17 @@ Design goals:
 
 ## Installation
 
-Install dependencies and run the CLI locally:
+```bash
+npm install -g github-portfolio-analyzer
+```
+
+Verify the installation:
 
 ```bash
-npm install
 github-portfolio-analyzer --version
 ```
 
-If the global binary is not available yet, use:
+If the global binary is not available, run directly:
 
 ```bash
 node bin/github-portfolio-analyzer.js --version
@@ -497,7 +500,7 @@ Each `portfolio.json.items[]` entry includes:
 - `effort`: `xs | s | m | l | xl`
 - `value`: `low | medium | high | very-high`
 - `nextAction`: `"<Verb> <target> — Done when: <measurable condition>"`
-- `taxonomyMeta`: per-field provenance (`default | user | inferred`)
+- `taxonomyMeta`: per-field provenance (`default | user | inferred`). For repositories, `sources.category` is always `user` (when set manually) or `inferred` (heuristic) — never `default`.
 
 `inventory.json.items[]` includes the same taxonomy fields and `taxonomyMeta` for repositories.
 
@@ -508,50 +511,133 @@ Each `portfolio.json.items[]` entry includes:
 - `meta` (generatedAt, asOfDate, owner, counts)
 - `summary` (state counts, top10 by score, now/next/later/park)
 - `matrix.completionByEffort` (`CL0..CL5` by `xs..xl`)
-- `items[]` with decision fields (`completionLevel`, `effortEstimate`, `priorityBand`, `priorityWhy`)
+- `items[]` with decision fields (`completionLevel`, `effortEstimate`, `priorityBand`, `priorityWhy`, `category`)
 
 ## Decision Model (Report)
 
+Every repository passes through a deterministic scoring pipeline:
+
+```mermaid
+flowchart LR
+    subgraph top [ ]
+        direction LR
+        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)
+    end
+    E --> F
+    E -. feeds .-> J
+    G -. feeds .-> J
+    J --> park([park]) & later([later]) & next([next]) & now([now])
+```
+
+### Score
+
+Each repository receives a score from 0 to 100 based on observable signals.
+Signal weights depend on the project's **category**, inferred automatically
+from its name, description, and GitHub topics.
+
+| Signal | product | tooling | library | content | learning | infra | experiment | template |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| baseline | — | — | — | **25** | **35** | — | **45** | **30** |
+| pushed (90d) | 25 | 25 | 20 | 25 | 20 | 25 | 20 | 10 |
+| README | 15 | 15 | 20 | 15 | 15 | 20 | 15 | **25** |
+| license | 10 | 10 | **20** | ✗ | ✗ | 10 | ✗ | 10 |
+| tests | 25 | 20 | **25** | ✗ | ✗ | 10 | ✗ | 5 |
+| stars > 1 | 5 | 5 | 10 | 5 | 5 | 5 | 5 | 10 |
+| updated (180d) | 20 | 25 | 5 | **30** | **25** | **30** | 15 | 10 |
+
+`✗` = irrelevant for this category (weight 0). `library` penalizes missing
+license most heavily. `experiment` and `learning` skip tests and license entirely.
+
+Example — a `content` repo with no license and no tests still scores 95:
+
+```
+"prompt-library"  category: content
+────────────────────────────────────
+baseline          +25
+pushed 10d ago    +25
+has README        +15
+has license        +0  (irrelevant for content)
+has tests          +0  (irrelevant for content)
+updated this month +30
+────────────────────────────────────
+score              95
+```
+
+See [docs/SCORING_MODEL.md](docs/SCORING_MODEL.md) for the full weight table
+and numeric examples for every category.
+
 ### Completion Level
 
-- `CL0`: no README
-- `CL1`: has README
-- `CL2`: has package.json, or non-JS repo with size >= 500 KB
-- `CL3`: CL2 + CI
-- `CL4`: CL3 + tests
-- `CL5`: CL4 + score >= 70
-- Ideas default to `CL0`
+Reflects structural maturity, regardless of category. Ideas always default to CL 0.
 
-### Effort Estimate
+| CL | Label | Condition |
+|---|---|---|
+| 0 | Concept only | no README, or `type: idea` |
+| 1 | Documented | has README |
+| 2 | Structured baseline | has `package.json` (or non-JS repo ≥ 500 KB) |
+| 3 | Automated workflow | CL 2 + CI |
+| 4 | Tested workflow | CL 3 + tests |
+| 5 | Production-ready candidate | CL 4 + score ≥ 70 |
 
-Uses taxonomy `effort` unless `effort` source is `default`.
-If defaulted, infer by size and completion:
+### Effort Estimate
 
-- `xs`: size < 100 KB and CL <= 2
-- `s`: size < 500 KB and CL <= 3
-- `m`: size < 5000 KB
-- `l`: size < 20000 KB
-- `xl`: size >= 20000 KB
+How much work remains to bring a project to its next meaningful state.
+Inferred automatically from repository size and completion level when not set manually.
+`effortEstimate` is a report-only field — it never overwrites the taxonomy `effort`.
 
-`effortEstimate` is a report field only; it does not overwrite taxonomy `effort`.
+| Estimate | Size | CL | What it means |
+|---|---|---|---|
+| `xs` | < 100 KB | ≤ 2 | A few hours. Easy to restart from scratch. |
+| `s` | < 500 KB | ≤ 3 | A day or two. Focused sprint. |
+| `m` | < 5 MB | any | About a week. Needs planning. |
+| `l` | < 20 MB | any | Multiple weeks. Real commitment required. |
+| `xl` | ≥ 20 MB | any | A long-term project. Strategic investment. |
 
 ### Priority Band
 
-Internal score calculation:
+The base score is adjusted by state, completion, and effort to produce a
+final `priorityScore`, which determines the band.
 
-- base: `score`
-- `+10` if state `active`
-- `+5` if state `stale`
-- `-20` if state `abandoned` or `archived`
-- `+10` if completion is CL1..CL3
-- `-10` if effortEstimate is `l` or `xl`
+| Modifier | Condition | Effect |
+|---|---|---|
+| State boost | `active` | +10 |
+| State boost | `stale` | +5 |
+| State penalty | `abandoned` or `archived` | −20 |
+| Quick-win boost | CL 1, 2, or 3 | +10 |
+| Effort penalty | `l` or `xl` | −10 |
+
+`priorityScore` has no lower bound — it can go negative.
+
+| Band | Range | Meaning |
+|---|---|---|
+| `park` | < 45 | Needs a decision before any investment. Abandoned, 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. |
 
-Band mapping:
+Example — modifiers can push a `park`-bound project below zero:
 
-- `now`: >= 80
-- `next`: 65..79
-- `later`: 45..64
-- `park`: < 45
+```
+"old-monolith"  category: product
+──────────────────────────────────
+baseline         0
+pushed 400d ago +0   (> 90 days)
+has README      +15
+has license     +10
+no tests        +0
+updated 200d ago +0  (> 180 days)
+──────────────────────────────────
+score            25
+
+state=abandoned  −20
+effort=xl        −10
+──────────────────────────────────
+priorityScore    −5  → park
+```
 
 ## Determinism and Time Rules
 
@@ -654,10 +740,13 @@ npm test
 Coverage includes:
 
 - activity/maturity/scoring boundaries
+- category inference from repository name, description, and topics
+- category-aware scoring weights and category preservation for user-specified values
 - taxonomy presence and provenance behavior
 - `nextAction` validation and normalization
 - portfolio merge determinism
 - report completion logic, priority mapping, and deterministic model generation
+- `category` propagation to report items and all summary bands
 
 ## Troubleshooting
 

package/analyzer.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "github-portfolio-analyzer",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "commands": [
     { "id": "analyze" },
     { "id": "ingest-ideas" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-portfolio-analyzer",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "CLI tool to analyze GitHub repos and portfolio ideas",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/paulo-raoni/github-portfolio-analyzer.git"
+    "url": "git+https://github.com/paulo-raoni/github-portfolio-analyzer.git"
   },
   "files": [
     "bin/",

package/schemas/portfolio-report.schema.json

@@ -176,7 +176,11 @@
           "type": "array",
           "items": { "type": "string" }
         },
-        "nextAction": { "type": "string" }
+        "nextAction": { "type": "string" },
+        "category": {
+          "type": "string",
+          "enum": ["product", "tooling", "library", "learning", "content", "infra", "experiment", "template"]
+        }
       }
     },
     "item": {
@@ -244,6 +248,17 @@
         },
         "htmlUrl": { "type": "string" },
         "homepage": { "type": "string" },
+        "category": {
+          "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,7 +6,16 @@ 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']),
@@ -15,14 +24,16 @@ const COMMAND_OPTIONS = {
 };
 
 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');
@@ -101,3 +117,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,32 @@ 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: [
+      { key: 'githubUsername', label: 'GitHub Username' },
+      { key: 'openaiKey', label: 'OpenAI API Key' },
+      { key: 'geminiKey', label: 'Gemini API Key' },
+      { key: 'anthropicKey', label: 'Anthropic API Key' }
+    ]
+  });
 
   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,6 +54,15 @@ 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);
@@ -73,17 +87,22 @@ export async function runAnalyzeCommand(options = {}) {
       const structuralHealth = await inspectRepositoryStructure(github, normalized);
       const activity = classifyActivity(normalized._pushedAt, asOfDate);
       const maturity = classifyMaturity(normalized.sizeKb);
-      const { score, scoreBreakdown } = scoreRepository(
-        { ...normalized, structuralHealth, pushedAt: normalized._pushedAt, updatedAt: normalized._updatedAt },
-        asOfDate
-      );
       const taxonomy = buildRepoTaxonomy({
         ...normalized,
         structuralHealth,
         activity,
-        maturity,
-        score
+        maturity
       });
+      const { score, scoreBreakdown } = scoreRepository(
+        {
+          ...normalized,
+          structuralHealth,
+          pushedAt: normalized._pushedAt,
+          updatedAt: normalized._updatedAt,
+          category: taxonomy.category
+        },
+        asOfDate
+      );
 
       return stripInternalFields({
         ...normalized,
@@ -106,22 +125,22 @@ export async function runAnalyzeCommand(options = {}) {
         hasTests: false,
         hasCi: false
       };
+      const taxonomy = buildRepoTaxonomy({
+        ...normalized,
+        structuralHealth: fallbackStructuralHealth,
+        activity,
+        maturity
+      });
       const { score, scoreBreakdown } = scoreRepository(
         {
           ...normalized,
           structuralHealth: fallbackStructuralHealth,
           pushedAt: normalized._pushedAt,
-          updatedAt: normalized._updatedAt
+          updatedAt: normalized._updatedAt,
+          category: taxonomy.category
         },
         asOfDate
       );
-      const taxonomy = buildRepoTaxonomy({
-        ...normalized,
-        structuralHealth: fallbackStructuralHealth,
-        activity,
-        maturity,
-        score
-      });
 
       return stripInternalFields({
         ...normalized,

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')

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/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

@@ -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,8 +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 } : {})
+      ...(!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 } : {})
     };
   });
 
@@ -259,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;
+    })
   };
 }
 
@@ -362,7 +381,8 @@ function toSummaryItem(item) {
     ...(item.priorityTag ? { priorityTag: item.priorityTag } : {}),
     priorityOverrides: item.priorityOverrides,
     priorityWhy: item.priorityWhy,
-    nextAction: item.nextAction
+    nextAction: item.nextAction,
+    ...(item.category != null ? { category: item.category } : {})
   };
 }
 

package/src/core/scoring.js

@@ -1,8 +1,49 @@
 import { daysSince } from './classification.js';
 
+const CATEGORY_WEIGHTS = {
+  product: {
+    pushedWithin90Days: 25, hasReadme: 15, hasLicense: 10,
+    hasTests: 25, starsOverOne: 5, updatedWithin180Days: 20, baseline: 0
+  },
+  tooling: {
+    pushedWithin90Days: 25, hasReadme: 15, hasLicense: 10,
+    hasTests: 20, starsOverOne: 5, updatedWithin180Days: 25, baseline: 0
+  },
+  library: {
+    pushedWithin90Days: 20, hasReadme: 20, hasLicense: 20,
+    hasTests: 25, starsOverOne: 10, updatedWithin180Days: 5, baseline: 0
+  },
+  content: {
+    pushedWithin90Days: 25, hasReadme: 15, hasLicense: 0,
+    hasTests: 0, starsOverOne: 5, updatedWithin180Days: 30, baseline: 25
+  },
+  learning: {
+    pushedWithin90Days: 20, hasReadme: 15, hasLicense: 0,
+    hasTests: 0, starsOverOne: 5, updatedWithin180Days: 25, baseline: 35
+  },
+  infra: {
+    pushedWithin90Days: 25, hasReadme: 20, hasLicense: 10,
+    hasTests: 10, starsOverOne: 5, updatedWithin180Days: 30, baseline: 0
+  },
+  experiment: {
+    pushedWithin90Days: 20, hasReadme: 15, hasLicense: 0,
+    hasTests: 0, starsOverOne: 5, updatedWithin180Days: 15, baseline: 45
+  },
+  template: {
+    pushedWithin90Days: 10, hasReadme: 25, hasLicense: 10,
+    hasTests: 5, starsOverOne: 10, updatedWithin180Days: 10, baseline: 30
+  }
+};
+
+const DEFAULT_WEIGHTS = CATEGORY_WEIGHTS.tooling;
+
 export function scoreRepository(repository, asOfDate) {
-  let score = 0;
+  const category = repository.category ?? 'tooling';
+  const weights = CATEGORY_WEIGHTS[category] ?? DEFAULT_WEIGHTS;
+
+  let score = weights.baseline ?? 0;
   const breakdown = {
+    baseline: weights.baseline ?? 0,
     pushedWithin90Days: 0,
     hasReadme: 0,
     hasLicense: 0,
@@ -11,34 +52,34 @@ export function scoreRepository(repository, asOfDate) {
     updatedWithin180Days: 0
   };
 
-  if (daysSince(repository.pushedAt, asOfDate) <= 90) {
-    score += 30;
-    breakdown.pushedWithin90Days = 30;
+  if (weights.pushedWithin90Days > 0 && daysSince(repository.pushedAt, asOfDate) <= 90) {
+    score += weights.pushedWithin90Days;
+    breakdown.pushedWithin90Days = weights.pushedWithin90Days;
   }
 
-  if (repository.structuralHealth?.hasReadme) {
-    score += 15;
-    breakdown.hasReadme = 15;
+  if (weights.hasReadme > 0 && repository.structuralHealth?.hasReadme) {
+    score += weights.hasReadme;
+    breakdown.hasReadme = weights.hasReadme;
   }
 
-  if (repository.structuralHealth?.hasLicense) {
-    score += 10;
-    breakdown.hasLicense = 10;
+  if (weights.hasLicense > 0 && repository.structuralHealth?.hasLicense) {
+    score += weights.hasLicense;
+    breakdown.hasLicense = weights.hasLicense;
   }
 
-  if (repository.structuralHealth?.hasTests) {
-    score += 20;
-    breakdown.hasTests = 20;
+  if (weights.hasTests > 0 && repository.structuralHealth?.hasTests) {
+    score += weights.hasTests;
+    breakdown.hasTests = weights.hasTests;
   }
 
-  if ((repository.stargazersCount ?? 0) > 1) {
-    score += 5;
-    breakdown.starsOverOne = 5;
+  if (weights.starsOverOne > 0 && (repository.stargazersCount ?? 0) > 1) {
+    score += weights.starsOverOne;
+    breakdown.starsOverOne = weights.starsOverOne;
   }
 
-  if (daysSince(repository.updatedAt, asOfDate) <= 180) {
-    score += 20;
-    breakdown.updatedWithin180Days = 20;
+  if (weights.updatedWithin180Days > 0 && daysSince(repository.updatedAt, asOfDate) <= 180) {
+    score += weights.updatedWithin180Days;
+    breakdown.updatedWithin180Days = weights.updatedWithin180Days;
   }
 
   return {

package/src/core/taxonomy.js

@@ -1,17 +1,57 @@
 import { formatNextAction, normalizeNextAction } from '../utils/nextAction.js';
 
+function inferRepoCategory(repository) {
+  const name = String(repository.name ?? '').toLowerCase();
+  const desc = String(repository.description ?? '').toLowerCase();
+  const topics = Array.isArray(repository.topics)
+    ? repository.topics.map((topic) => String(topic).toLowerCase())
+    : [];
+  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)) {
+    return 'learning';
+  }
+
+  if (/\b(template|templates|boilerplate|starter|scaffold|skeleton|seed|base|init)\b/.test(all)) {
+    return 'template';
+  }
+
+  if (/\b(lib|library|sdk|package|npm|module|plugin|extension|addon|util|utils|helper|helpers)\b/.test(all)) {
+    return 'library';
+  }
+
+  if (/\b(infra|infrastructure|docker|kubernetes|k8s|ci|cd|pipeline|deploy|devops|ansible|terraform|nginx|proxy)\b/.test(all)) {
+    return 'infra';
+  }
+
+  if (/\b(poc|proof|experiment|spike|demo|prototype|sandbox|playground|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)) {
+    return 'product';
+  }
+
+  return 'tooling';
+}
+
 export function buildRepoTaxonomy(repository) {
   const activityState = repository.activity;
   const state = repository.archived ? 'archived' : normalizeState(activityState, 'active');
 
-  const category = 'tooling';
+  const userCategory = normalizeCategory(repository.category);
+  const category = userCategory ?? inferRepoCategory(repository);
   const strategy = 'maintenance';
   const effort = 'm';
   const value = 'medium';
   const nextAction = defaultRepoNextAction(state);
 
   const sources = {
-    category: 'default',
+    category: userCategory ? 'user' : 'inferred',
     state: repository.archived ? 'inferred' : 'inferred',
     strategy: 'default',
     effort: 'default',

package/src/github/repos.js

@@ -1,5 +1,39 @@
 const PAGE_SIZE = 100;
 
+/**
+ * Classifies a fork as active or passive.
+ * Active forks have commits ahead of the upstream default branch.
+ */
+export async function classifyFork(client, repo) {
+  if (!repo?.fork) {
+    return null;
+  }
+
+  const parent = repo.parent;
+  if (!parent) {
+    return 'passive';
+  }
+
+  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 'passive';
+  }
+
+  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 'passive';
+  }
+}
+
 export async function fetchAllRepositories(client) {
   const repositories = [];
 
@@ -26,6 +60,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);
+      })
+    );
+  }
+
   return repositories;
 }
 
@@ -39,6 +84,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/report.js

@@ -108,7 +108,8 @@ function renderAsciiBandSection(title, items) {
   }
 
   items.slice(0, 5).forEach((item, index) => {
-    lines.push(`${index + 1}) ${item.slug} — Score ${item.score} — CL${item.completionLevel} — Effort ${item.effortEstimate} — State ${item.state}`);
+    const categoryPrefix = item.category == null ? '' : `[${item.category}] `;
+    lines.push(`${index + 1}) ${categoryPrefix}${item.slug} — Score ${item.score} — CL${item.completionLevel} — Effort ${item.effortEstimate} — State ${item.state}`);
     lines.push(`   Why: ${item.priorityWhy?.join('; ') ?? ''}`);
     lines.push(`   Next: ${item.nextAction}`);
   });
@@ -129,7 +130,8 @@ function renderMarkdownBandSection(title, items) {
   }
 
   items.slice(0, 5).forEach((item, index) => {
-    lines.push(`${index + 1}. **${item.slug}** — Score ${item.score} — CL${item.completionLevel} — Effort ${item.effortEstimate} — State ${item.state}`);
+    const categoryPrefix = item.category == null ? '' : `\`${item.category}\` `;
+    lines.push(`${index + 1}. ${categoryPrefix}**${item.slug}** — Score ${item.score} — CL${item.completionLevel} — Effort ${item.effortEstimate} — State ${item.state}`);
     lines.push(`   - Why: ${item.priorityWhy?.join('; ') ?? ''}`);
     lines.push(`   - Next: ${item.nextAction}`);
   });

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;