prjct-cli 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,12 +1,91 @@
 # Changelog
 
+## [1.5.0] - 2026-02-06
+
+### Features
+
+- add citation format for context sources in templates (PRJ-113) (#117)
+
+
+## [1.4.2] - 2026-02-06
+
+### Features
+
+- **Source citations in context files (PRJ-113)**: All generated context files now include `<!-- source: file, type -->` HTML comments showing where each section's data was detected from
+
+### Implementation Details
+
+- Added `SourceInfo` type and `ContextSources` interface with `cite()` helper (`core/utils/citations.ts`)
+- Extended `ProjectContext` with optional `sources` field — backward compatible, falls back to `defaultSources()`
+- Added `buildSources()` to `sync-service.ts` — maps detected ecosystem/commands data to their source files (package.json, lock files, Cargo.toml, etc.)
+- Citations added to 4 markdown formatters: Claude, Cursor, Windsurf, Copilot. Continue.dev skipped (JSON has no comment syntax)
+- Context generator CLAUDE.md also updated with citation support
+- Source types: `detected` (from files), `user-defined` (from config), `inferred` (from heuristics)
+
+### Learnings
+
+- `context-generator.ts` and `formatters.ts` both independently generate CLAUDE.md content — both must be updated for consistent citations
+- Sources can be determined post-detection from data values rather than threading metadata through every detection method
+- Optional fields with fallback defaults (`sources?`) maintain backward compatibility without breaking existing callers
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync --yes` — verify generated context files contain `<!-- source: ... -->` comments
+2. Check CLAUDE.md citations before: THIS PROJECT, Commands, Code Conventions, PROJECT STATE
+3. Check `.cursor/rules/prjct.mdc` citations before Tech Stack and Commands
+4. Check `.windsurf/rules/prjct.md` citations before Stack and Commands
+5. Check `.github/copilot-instructions.md` citations before Project Info and Commands
+6. Verify `.continue/config.json` unchanged (JSON has no comments)
+7. Run `bun test` — all 416 tests pass
+
+#### For Users
+**What changed:** Context files now show where data came from via HTML comments
+**How to use:** Run `p. sync` — citations appear automatically
+**Breaking changes:** None
+
+## [1.4.1] - 2026-02-06
+
+### Improvements
+
+- **Better error messages for invalid commands (PRJ-98)**: Consistent, helpful CLI errors with did-you-mean suggestions and required parameter validation
+
+### Implementation Details
+
+- Added `UNKNOWN_COMMAND` and `MISSING_PARAM` error codes to centralized error catalog (`core/utils/error-messages.ts`)
+- Added `validateCommandParams()` — parses `CommandMeta.params` convention (`<required>` vs `[optional]`) and validates against actual CLI args before command execution
+- Added `findClosestCommand()` with Levenshtein edit distance (threshold ≤ 2) for did-you-mean suggestions on typos
+- All error paths now use `out.failWithHint()` for consistent formatting with hints, docs links, and file references
+- Deprecated and unimplemented command errors also upgraded to use `failWithHint()`
+
+### Learnings
+
+- `bin/prjct.ts` intercepts many commands (start, context, hooks, doctor, etc.) before `core/index.ts` — changes to dispatch only affect commands that reach core
+- Template-only commands (e.g. `task`) are defined in `command-data.ts` but not registered in the command registry — they don't get param validation via CLI
+- Levenshtein edit distance is simple to implement (~15 lines) and effective for CLI typo suggestions
+
+### Test Plan
+
+#### For QA
+1. `prjct xyzzy` → "Unknown command: xyzzy" with help hint
+2. `prjct snyc` → "Did you mean 'prjct sync'?"
+3. `prjct shp` → "Did you mean 'prjct ship'?"
+4. `prjct bug` (no args) → "Missing required parameter: description" with usage
+5. `prjct idea` (no args) → "Missing required parameter: description" with usage
+6. `prjct sync --yes` → works normally (no regression)
+7. `prjct dash compact` → works normally (no regression)
+
+#### For Users
+**What changed:** CLI now shows helpful error messages with suggestions when you mistype a command or forget a required argument.
+**How to use:** Just use prjct normally — errors are now more helpful automatically.
+**Breaking changes:** None
+
 ## [1.4.0] - 2026-02-06
 
 ### Features
 
 - programmatic verification checks for sync workflow (PRJ-106) (#115)
 
-
 ## [1.3.1] - 2026-02-06
 
 ### Features

package/core/__tests__/ai-tools/formatters.test.ts

@@ -2,6 +2,7 @@
  * Tests for AI Tools Formatters
  *
  * @see PRJ-122
+ * @see PRJ-113 (citation support)
  */
 
 import { describe, expect, test } from 'bun:test'
@@ -15,6 +16,7 @@ import {
   type ProjectContext,
 } from '../../ai-tools/formatters'
 import { AI_TOOLS, getAIToolConfig } from '../../ai-tools/registry'
+import { type ContextSources, cite, defaultSources } from '../../utils/citations'
 
 // =============================================================================
 // Test Fixtures
@@ -356,3 +358,119 @@ describe('Formatter Edge Cases', () => {
     expect(claudeResult).toContain('@scope/my-project')
   })
 })
+
+// =============================================================================
+// Citation Tests (PRJ-113)
+// =============================================================================
+
+const mockSources: ContextSources = {
+  name: { file: 'package.json', type: 'detected' },
+  version: { file: 'package.json', type: 'detected' },
+  ecosystem: { file: 'package.json', type: 'detected' },
+  languages: { file: 'package.json', type: 'detected' },
+  frameworks: { file: 'package.json', type: 'detected' },
+  commands: { file: 'bun.lockb', type: 'detected' },
+  projectType: { file: 'file count + frameworks', type: 'inferred' },
+  git: { file: 'git', type: 'detected' },
+}
+
+const ctxWithSources: ProjectContext = {
+  ...mockContext,
+  sources: mockSources,
+}
+
+describe('cite() helper', () => {
+  test('generates HTML comment with file and type', () => {
+    const result = cite({ file: 'package.json', type: 'detected' })
+    expect(result).toBe('<!-- source: package.json, detected -->')
+  })
+
+  test('supports inferred type', () => {
+    const result = cite({ file: 'file count + frameworks', type: 'inferred' })
+    expect(result).toBe('<!-- source: file count + frameworks, inferred -->')
+  })
+
+  test('supports user-defined type', () => {
+    const result = cite({ file: 'prjct.yaml', type: 'user-defined' })
+    expect(result).toBe('<!-- source: prjct.yaml, user-defined -->')
+  })
+})
+
+describe('defaultSources()', () => {
+  test('returns all source fields', () => {
+    const sources = defaultSources()
+    expect(sources.name).toBeDefined()
+    expect(sources.version).toBeDefined()
+    expect(sources.ecosystem).toBeDefined()
+    expect(sources.languages).toBeDefined()
+    expect(sources.frameworks).toBeDefined()
+    expect(sources.commands).toBeDefined()
+    expect(sources.projectType).toBeDefined()
+    expect(sources.git).toBeDefined()
+  })
+
+  test('git source is always "git"', () => {
+    const sources = defaultSources()
+    expect(sources.git.file).toBe('git')
+    expect(sources.git.type).toBe('detected')
+  })
+})
+
+describe('Citation integration', () => {
+  test('Claude format includes source citations', () => {
+    const result = formatForClaude(ctxWithSources, AI_TOOLS.claude)
+
+    expect(result).toContain('<!-- source: package.json, detected -->')
+    expect(result).toContain('<!-- source: bun.lockb, detected -->')
+  })
+
+  test('Cursor format includes source citations', () => {
+    const result = formatForCursor(ctxWithSources, AI_TOOLS.cursor)
+
+    expect(result).toContain('<!-- source: package.json, detected -->')
+    expect(result).toContain('<!-- source: bun.lockb, detected -->')
+  })
+
+  test('Windsurf format includes source citations', () => {
+    const result = formatForWindsurf(ctxWithSources, AI_TOOLS.windsurf)
+
+    expect(result).toContain('<!-- source: package.json, detected -->')
+    expect(result).toContain('<!-- source: bun.lockb, detected -->')
+  })
+
+  test('Copilot format includes source citations', () => {
+    const result = formatForCopilot(ctxWithSources, AI_TOOLS.copilot)
+
+    expect(result).toContain('<!-- source: package.json, detected -->')
+    expect(result).toContain('<!-- source: bun.lockb, detected -->')
+  })
+
+  test('formatters work without sources (backward compatible)', () => {
+    const ctxNoSources = { ...mockContext }
+    delete ctxNoSources.sources
+
+    // Should not throw
+    expect(() => formatForClaude(ctxNoSources, AI_TOOLS.claude)).not.toThrow()
+    expect(() => formatForCursor(ctxNoSources, AI_TOOLS.cursor)).not.toThrow()
+    expect(() => formatForWindsurf(ctxNoSources, AI_TOOLS.windsurf)).not.toThrow()
+    expect(() => formatForCopilot(ctxNoSources, AI_TOOLS.copilot)).not.toThrow()
+
+    // Should still contain default citation comments
+    const result = formatForClaude(ctxNoSources, AI_TOOLS.claude)
+    expect(result).toContain('<!-- source:')
+  })
+
+  test('Claude format has citations before each major section', () => {
+    const result = formatForClaude(ctxWithSources, AI_TOOLS.claude)
+
+    // Ecosystem citation before project type
+    const ecosystemIdx = result.indexOf('<!-- source: package.json, detected -->')
+    const projectTypeIdx = result.indexOf('**Type:**')
+    expect(ecosystemIdx).toBeLessThan(projectTypeIdx)
+
+    // Commands citation before commands table
+    const commandsCiteIdx = result.indexOf('<!-- source: bun.lockb, detected -->')
+    const commandsTableIdx = result.indexOf('| Action | Command |')
+    expect(commandsCiteIdx).toBeLessThan(commandsTableIdx)
+  })
+})

package/core/ai-tools/formatters.ts

@@ -8,6 +8,7 @@
  * - Windsurf: Similar to Cursor
  */
 
+import { type ContextSources, cite, defaultSources } from '../utils/citations'
 import type { AIToolConfig } from './registry'
 
 export interface ProjectContext {
@@ -35,6 +36,7 @@ export interface ProjectContext {
     workflow: string[]
     domain: string[]
   }
+  sources?: ContextSources
 }
 
 /**
@@ -42,6 +44,8 @@ export interface ProjectContext {
  * Detailed markdown with full context
  */
 export function formatForClaude(ctx: ProjectContext, _config: AIToolConfig): string {
+  const s = ctx.sources || defaultSources()
+
   return `# ${ctx.name} - Project Rules
 <!-- projectId: ${ctx.projectId} -->
 <!-- Generated: ${new Date().toISOString()} -->
@@ -49,11 +53,13 @@ export function formatForClaude(ctx: ProjectContext, _config: AIToolConfig): str
 
 ## THIS PROJECT (${ctx.ecosystem})
 
+${cite(s.ecosystem)}
 **Type:** ${ctx.projectType}
 **Path:** ${ctx.repoPath}
 
 ### Commands (USE THESE, NOT OTHERS)
 
+${cite(s.commands)}
 | Action | Command |
 |--------|---------|
 | Install dependencies | \`${ctx.commands.install}\` |
@@ -65,7 +71,9 @@ export function formatForClaude(ctx: ProjectContext, _config: AIToolConfig): str
 
 ### Code Conventions
 
+${cite(s.languages)}
 - **Languages**: ${ctx.languages.join(', ') || 'Not detected'}
+${cite(s.frameworks)}
 - **Frameworks**: ${ctx.frameworks.join(', ') || 'Not detected'}
 
 ---
@@ -93,6 +101,7 @@ p. sync → p. task "desc" → [work] → p. done → p. ship
 
 ## PROJECT STATE
 
+${cite(s.name)}
 | Field | Value |
 |-------|-------|
 | Name | ${ctx.name} |
@@ -120,6 +129,7 @@ Load from \`~/.prjct-cli/projects/${ctx.projectId}/agents/\`:
  * @see https://cursor.com/docs/context/rules
  */
 export function formatForCursor(ctx: ProjectContext, _config: AIToolConfig): string {
+  const s = ctx.sources || defaultSources()
   const lines: string[] = []
 
   // MDC format with YAML frontmatter
@@ -135,6 +145,7 @@ export function formatForCursor(ctx: ProjectContext, _config: AIToolConfig): str
   lines.push('')
 
   // Tech stack
+  lines.push(cite(s.languages))
   lines.push('## Tech Stack')
   if (ctx.languages.length > 0) {
     lines.push(`- Languages: ${ctx.languages.join(', ')}`)
@@ -145,6 +156,7 @@ export function formatForCursor(ctx: ProjectContext, _config: AIToolConfig): str
   lines.push('')
 
   // Commands
+  lines.push(cite(s.commands))
   lines.push('## Commands')
   lines.push(`- Install: \`${ctx.commands.install}\``)
   lines.push(`- Dev: \`${ctx.commands.dev}\``)
@@ -175,6 +187,7 @@ export function formatForCursor(ctx: ProjectContext, _config: AIToolConfig): str
  * Minimal bullet points
  */
 export function formatForCopilot(ctx: ProjectContext, _config: AIToolConfig): string {
+  const s = ctx.sources || defaultSources()
   const lines: string[] = []
 
   lines.push('# Copilot Instructions')
@@ -183,6 +196,7 @@ export function formatForCopilot(ctx: ProjectContext, _config: AIToolConfig): st
   lines.push('')
 
   // Key info
+  lines.push(cite(s.ecosystem))
   lines.push('## Project Info')
   lines.push(`- Type: ${ctx.projectType}`)
   lines.push(`- Stack: ${ctx.frameworks.join(', ') || ctx.ecosystem}`)
@@ -196,6 +210,7 @@ export function formatForCopilot(ctx: ProjectContext, _config: AIToolConfig): st
   lines.push('')
 
   // Commands
+  lines.push(cite(s.commands))
   lines.push('## Commands')
   lines.push(`- Test: \`${ctx.commands.test}\``)
   lines.push(`- Build: \`${ctx.commands.build}\``)
@@ -210,6 +225,7 @@ export function formatForCopilot(ctx: ProjectContext, _config: AIToolConfig): st
  * @see https://docs.windsurf.com/windsurf/cascade/memories
  */
 export function formatForWindsurf(ctx: ProjectContext, _config: AIToolConfig): string {
+  const s = ctx.sources || defaultSources()
   const lines: string[] = []
 
   // YAML frontmatter (Windsurf uses trigger: always_on instead of alwaysApply)
@@ -226,6 +242,7 @@ export function formatForWindsurf(ctx: ProjectContext, _config: AIToolConfig): s
   lines.push('')
 
   // Tech stack (concise)
+  lines.push(cite(s.languages))
   lines.push('## Stack')
   lines.push(`- ${ctx.languages.join(', ')}`)
   if (ctx.frameworks.length > 0) {
@@ -234,6 +251,7 @@ export function formatForWindsurf(ctx: ProjectContext, _config: AIToolConfig): s
   lines.push('')
 
   // Commands (essential only)
+  lines.push(cite(s.commands))
   lines.push('## Commands')
   lines.push('```bash')
   lines.push(`# Install`)

package/core/index.ts

@@ -15,6 +15,7 @@ import type { CommandMeta } from './commands/registry'
 import { detectAllProviders, detectAntigravity } from './infrastructure/ai-provider'
 import configManager from './infrastructure/config-manager'
 import { sessionTracker } from './services/session-tracker'
+import { getError } from './utils/error-messages'
 import out from './utils/output'
 
 interface ParsedCommandArgs {
@@ -53,27 +54,34 @@ async function main(): Promise<void> {
     const cmd = commandRegistry.getByName(commandName)
 
     if (!cmd) {
-      console.error(`Unknown command: ${commandName}`)
-      console.error(`\nUse 'prjct --help' to see available commands.`)
+      const suggestion = findClosestCommand(commandName)
+      const hint = suggestion
+        ? `Did you mean 'prjct ${suggestion}'? Run 'prjct --help' for all commands`
+        : "Run 'prjct --help' to see available commands"
+      out.failWithHint(
+        getError('UNKNOWN_COMMAND', { message: `Unknown command: ${commandName}`, hint })
+      )
       out.end()
       process.exit(1)
     }
 
     // 2. Check if deprecated
     if (cmd.deprecated) {
-      console.error(`Command '${commandName}' is deprecated.`)
-      if (cmd.replacedBy) {
-        console.error(`Use 'prjct ${cmd.replacedBy}' instead.`)
-      }
+      const hint = cmd.replacedBy
+        ? `Use 'prjct ${cmd.replacedBy}' instead`
+        : "Run 'prjct --help' to see available commands"
+      out.failWithHint({ message: `Command '${commandName}' is deprecated`, hint })
       out.end()
       process.exit(1)
     }
 
     // 3. Check if implemented
     if (!cmd.implemented) {
-      console.error(`Command '${commandName}' exists but is not yet implemented.`)
-      console.error(`Check the roadmap or contribute: https://github.com/jlopezlira/prjct-cli`)
-      console.error(`\nUse 'prjct --help' to see available commands.`)
+      out.failWithHint({
+        message: `Command '${commandName}' is not yet implemented`,
+        hint: "Run 'prjct --help' to see available commands",
+        docs: 'https://github.com/jlopezlira/prjct-cli',
+      })
       out.end()
       process.exit(1)
     }
@@ -81,7 +89,15 @@ async function main(): Promise<void> {
     // 4. Parse arguments
     const { parsedArgs, options } = parseCommandArgs(cmd, rawArgs)
 
-    // 4.5. Session tracking — touch/create session before command execution
+    // 4.5. Validate required params
+    const paramError = validateCommandParams(cmd, parsedArgs)
+    if (paramError) {
+      out.failWithHint(paramError)
+      out.end()
+      process.exit(1)
+    }
+
+    // 4.6. Session tracking — touch/create session before command execution
     let projectId: string | null = null
     const commandStartTime = Date.now()
     try {
@@ -193,6 +209,71 @@ async function main(): Promise<void> {
   }
 }
 
+/**
+ * Validate that required params are provided
+ * Parses CommandMeta.params: <required> vs [optional]
+ */
+function validateCommandParams(
+  cmd: CommandMeta,
+  parsedArgs: string[]
+): import('./utils/error-messages').ErrorWithHint | null {
+  if (!cmd.params) return null
+
+  // Extract required params: tokens wrapped in <angle brackets>
+  const requiredParams = cmd.params.match(/<[^>]+>/g)
+  if (!requiredParams || requiredParams.length === 0) return null
+
+  // Check if enough positional args provided
+  if (parsedArgs.length < requiredParams.length) {
+    const paramNames = requiredParams.map((p) => p.slice(1, -1)).join(', ')
+    const usage = cmd.usage.terminal || `prjct ${cmd.name} ${cmd.params}`
+    return getError('MISSING_PARAM', {
+      message: `Missing required parameter: ${paramNames}`,
+      hint: `Usage: ${usage}`,
+    })
+  }
+
+  return null
+}
+
+/**
+ * Find closest matching command name for did-you-mean suggestions
+ * Uses Levenshtein edit distance — suggests if distance <= 2
+ */
+function findClosestCommand(input: string): string | null {
+  const allNames = commandRegistry.getAll().map((c) => c.name)
+  let best: string | null = null
+  let bestDist = Infinity
+
+  for (const name of allNames) {
+    const dist = editDistance(input.toLowerCase(), name.toLowerCase())
+    if (dist < bestDist) {
+      bestDist = dist
+      best = name
+    }
+  }
+
+  // Only suggest if edit distance is at most 2
+  return bestDist <= 2 ? best : null
+}
+
+function editDistance(a: string, b: string): number {
+  const m = a.length
+  const n = b.length
+  const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0))
+  for (let i = 0; i <= m; i++) dp[i][0] = i
+  for (let j = 0; j <= n; j++) dp[0][j] = j
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1])
+    }
+  }
+  return dp[m][n]
+}
+
 /**
  * Parse command arguments dynamically
  */

package/core/services/context-generator.ts

@@ -12,6 +12,7 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import pathManager from '../infrastructure/path-manager'
+import { type ContextSources, cite, defaultSources } from '../utils/citations'
 import dateHelper from '../utils/date-helper'
 import { mergePreservedSections, validatePreserveBlocks } from '../utils/preserve-sections'
 import { NestedContextResolver } from './nested-context-resolver'
@@ -103,13 +104,14 @@ export class ContextFileGenerator {
     git: GitData,
     stats: ProjectStats,
     commands: Commands,
-    agents: AgentInfo[]
+    agents: AgentInfo[],
+    sources?: ContextSources
   ): Promise<string[]> {
     const contextPath = path.join(this.config.globalPath, 'context')
 
     // Generate all context files IN PARALLEL
     await Promise.all([
-      this.generateClaudeMd(contextPath, git, stats, commands, agents),
+      this.generateClaudeMd(contextPath, git, stats, commands, agents, sources),
       this.generateNowMd(contextPath),
       this.generateNextMd(contextPath),
       this.generateIdeasMd(contextPath),
@@ -137,10 +139,12 @@ export class ContextFileGenerator {
     git: GitData,
     stats: ProjectStats,
     commands: Commands,
-    agents: AgentInfo[]
+    agents: AgentInfo[],
+    sources?: ContextSources
   ): Promise<void> {
     const workflowAgents = agents.filter((a) => a.type === 'workflow').map((a) => a.name)
     const domainAgents = agents.filter((a) => a.type === 'domain').map((a) => a.name)
+    const s = sources || defaultSources()
 
     const content = `# ${stats.name} - Project Rules
 <!-- projectId: ${this.config.projectId} -->
@@ -149,11 +153,13 @@ export class ContextFileGenerator {
 
 ## THIS PROJECT (${stats.ecosystem})
 
+${cite(s.ecosystem)}
 **Type:** ${stats.projectType}
 **Path:** ${this.config.projectPath}
 
 ### Commands (USE THESE, NOT OTHERS)
 
+${cite(s.commands)}
 | Action | Command |
 |--------|---------|
 | Install dependencies | \`${commands.install}\` |
@@ -165,7 +171,9 @@ export class ContextFileGenerator {
 
 ### Code Conventions
 
+${cite(s.languages)}
 - **Languages**: ${stats.languages.join(', ') || 'Not detected'}
+${cite(s.frameworks)}
 - **Frameworks**: ${stats.frameworks.join(', ') || 'Not detected'}
 
 ---
@@ -193,6 +201,7 @@ p. sync → p. task "desc" → [work] → p. done → p. ship
 
 ## PROJECT STATE
 
+${cite(s.name)}
 | Field | Value |
 |-------|-------|
 | Name | ${stats.name} |

package/core/services/sync-service.ts

@@ -30,6 +30,7 @@ import commandInstaller from '../infrastructure/command-installer'
 import configManager from '../infrastructure/config-manager'
 import pathManager from '../infrastructure/path-manager'
 import { metricsStorage } from '../storage/metrics-storage'
+import { type ContextSources, defaultSources, type SourceInfo } from '../utils/citations'
 import dateHelper from '../utils/date-helper'
 import { ContextFileGenerator } from './context-generator'
 import type { SyncDiff } from './diff-generator'
@@ -202,7 +203,8 @@ class SyncService {
       // 4. Generate all files (depends on gathered data)
       const agents = await this.generateAgents(stack, stats)
       const skills = this.configureSkills(agents)
-      const contextFiles = await this.generateContextFiles(git, stats, commands, agents)
+      const sources = this.buildSources(stats, commands)
+      const contextFiles = await this.generateContextFiles(git, stats, commands, agents, sources)
 
       // 5. Generate AI tool context files (multi-agent output)
       const projectContext: ProjectContext = {
@@ -223,6 +225,7 @@ class SyncService {
           workflow: agents.filter((a) => a.type === 'workflow').map((a) => a.name),
           domain: agents.filter((a) => a.type === 'domain').map((a) => a.name),
         },
+        sources,
       }
 
       const aiToolResults = await generateAIToolContexts(
@@ -535,6 +538,54 @@ class SyncService {
     return commands
   }
 
+  // ==========================================================================
+  // SOURCE CITATIONS
+  // ==========================================================================
+
+  private buildSources(stats: ProjectStats, commands: Commands): ContextSources {
+    const sources = defaultSources()
+
+    // Determine ecosystem source file
+    const ecosystemFiles: Record<string, string> = {
+      JavaScript: 'package.json',
+      Rust: 'Cargo.toml',
+      Go: 'go.mod',
+      Python: 'pyproject.toml',
+    }
+    const ecosystemFile = ecosystemFiles[stats.ecosystem] || 'filesystem'
+    const detected = (file: string): SourceInfo => ({ file, type: 'detected' })
+    const inferred = (file: string): SourceInfo => ({ file, type: 'inferred' })
+
+    sources.ecosystem = detected(ecosystemFile)
+    sources.name = detected(ecosystemFile)
+    sources.version = detected(ecosystemFile)
+    sources.languages = detected(ecosystemFile)
+    sources.frameworks = detected(ecosystemFile)
+
+    // Commands source is the lock file or ecosystem file
+    if (commands.install.startsWith('bun')) {
+      sources.commands = detected('bun.lockb')
+    } else if (commands.install.startsWith('pnpm')) {
+      sources.commands = detected('pnpm-lock.yaml')
+    } else if (commands.install === 'yarn') {
+      sources.commands = detected('yarn.lock')
+    } else if (commands.install.startsWith('cargo')) {
+      sources.commands = detected('Cargo.toml')
+    } else if (commands.install.startsWith('go')) {
+      sources.commands = detected('go.mod')
+    } else {
+      sources.commands = detected('package.json')
+    }
+
+    // Project type is inferred from file count + framework count
+    sources.projectType = inferred('file count + frameworks')
+
+    // Git is always from git
+    sources.git = detected('git')
+
+    return sources
+  }
+
   // ==========================================================================
   // STACK DETECTION
   // ==========================================================================
@@ -757,7 +808,8 @@ You are the ${name} expert for this project. Apply best practices for the detect
     git: GitData,
     stats: ProjectStats,
     commands: Commands,
-    agents: AgentInfo[]
+    agents: AgentInfo[],
+    sources?: ContextSources
   ): Promise<string[]> {
     const generator = new ContextFileGenerator({
       projectId: this.projectId!,
@@ -765,7 +817,13 @@ You are the ${name} expert for this project. Apply best practices for the detect
       globalPath: this.globalPath,
     })
 
-    return generator.generate({ branch: git.branch, commits: git.commits }, stats, commands, agents)
+    return generator.generate(
+      { branch: git.branch, commits: git.commits },
+      stats,
+      commands,
+      agents,
+      sources
+    )
   }
 
   // ==========================================================================

package/core/utils/citations.ts

@@ -0,0 +1,53 @@
+/**
+ * Citation utilities for context source tracking
+ *
+ * Generates HTML comments indicating where each section's data came from.
+ * Source types: detected (from files), user-defined (from config), inferred (from heuristics)
+ *
+ * @see PRJ-113
+ */
+
+export type SourceType = 'detected' | 'user-defined' | 'inferred'
+
+export interface SourceInfo {
+  file: string
+  type: SourceType
+}
+
+export interface ContextSources {
+  name: SourceInfo
+  version: SourceInfo
+  ecosystem: SourceInfo
+  languages: SourceInfo
+  frameworks: SourceInfo
+  commands: SourceInfo
+  projectType: SourceInfo
+  git: SourceInfo
+}
+
+/**
+ * Generate an HTML citation comment
+ *
+ * @example cite({ file: 'package.json', type: 'detected' })
+ * // => '<!-- source: package.json, detected -->'
+ */
+export function cite(source: SourceInfo): string {
+  return `<!-- source: ${source.file}, ${source.type} -->`
+}
+
+/**
+ * Create default sources (all unknown) - used as fallback
+ */
+export function defaultSources(): ContextSources {
+  const unknown: SourceInfo = { file: 'unknown', type: 'detected' }
+  return {
+    name: { ...unknown },
+    version: { ...unknown },
+    ecosystem: { ...unknown },
+    languages: { ...unknown },
+    frameworks: { ...unknown },
+    commands: { ...unknown },
+    projectType: { ...unknown },
+    git: { file: 'git', type: 'detected' },
+  }
+}

package/core/utils/error-messages.ts

@@ -128,6 +128,17 @@ export const ERRORS = {
     hint: "Run 'prjct start' to configure your provider",
   },
 
+  // Command errors
+  UNKNOWN_COMMAND: {
+    message: 'Unknown command',
+    hint: "Run 'prjct --help' to see available commands",
+  },
+
+  MISSING_PARAM: {
+    message: 'Missing required parameter',
+    hint: 'Check command usage below',
+  },
+
   // Generic
   UNKNOWN: {
     message: 'An unexpected error occurred',

package/dist/bin/prjct.mjs

@@ -2225,6 +2225,15 @@ var init_error_messages = __esm({
         message: "AI provider not configured for prjct",
         hint: "Run 'prjct start' to configure your provider"
       },
+      // Command errors
+      UNKNOWN_COMMAND: {
+        message: "Unknown command",
+        hint: "Run 'prjct --help' to see available commands"
+      },
+      MISSING_PARAM: {
+        message: "Missing required parameter",
+        hint: "Check command usage below"
+      },
       // Generic
       UNKNOWN: {
         message: "An unexpected error occurred",
@@ -20378,8 +20387,34 @@ var init_staleness_checker = __esm({
   }
 });
 
+// core/utils/citations.ts
+function cite(source) {
+  return `<!-- source: ${source.file}, ${source.type} -->`;
+}
+function defaultSources() {
+  const unknown = { file: "unknown", type: "detected" };
+  return {
+    name: { ...unknown },
+    version: { ...unknown },
+    ecosystem: { ...unknown },
+    languages: { ...unknown },
+    frameworks: { ...unknown },
+    commands: { ...unknown },
+    projectType: { ...unknown },
+    git: { file: "git", type: "detected" }
+  };
+}
+var init_citations = __esm({
+  "core/utils/citations.ts"() {
+    "use strict";
+    __name(cite, "cite");
+    __name(defaultSources, "defaultSources");
+  }
+});
+
 // core/ai-tools/formatters.ts
 function formatForClaude(ctx, _config) {
+  const s = ctx.sources || defaultSources();
   return `# ${ctx.name} - Project Rules
 <!-- projectId: ${ctx.projectId} -->
 <!-- Generated: ${(/* @__PURE__ */ new Date()).toISOString()} -->
@@ -20387,11 +20422,13 @@ function formatForClaude(ctx, _config) {
 
 ## THIS PROJECT (${ctx.ecosystem})
 
+${cite(s.ecosystem)}
 **Type:** ${ctx.projectType}
 **Path:** ${ctx.repoPath}
 
 ### Commands (USE THESE, NOT OTHERS)
 
+${cite(s.commands)}
 | Action | Command |
 |--------|---------|
 | Install dependencies | \`${ctx.commands.install}\` |
@@ -20403,7 +20440,9 @@ function formatForClaude(ctx, _config) {
 
 ### Code Conventions
 
+${cite(s.languages)}
 - **Languages**: ${ctx.languages.join(", ") || "Not detected"}
+${cite(s.frameworks)}
 - **Frameworks**: ${ctx.frameworks.join(", ") || "Not detected"}
 
 ---
@@ -20431,6 +20470,7 @@ p. sync \u2192 p. task "desc" \u2192 [work] \u2192 p. done \u2192 p. ship
 
 ## PROJECT STATE
 
+${cite(s.name)}
 | Field | Value |
 |-------|-------|
 | Name | ${ctx.name} |
@@ -20451,6 +20491,7 @@ Load from \`~/.prjct-cli/projects/${ctx.projectId}/agents/\`:
 `;
 }
 function formatForCursor(ctx, _config) {
+  const s = ctx.sources || defaultSources();
   const lines = [];
   lines.push("---");
   lines.push(`description: prjct context for ${ctx.name}`);
@@ -20460,6 +20501,7 @@ function formatForCursor(ctx, _config) {
   lines.push("");
   lines.push(`You are working on ${ctx.name}, a ${ctx.projectType} ${ctx.ecosystem} project.`);
   lines.push("");
+  lines.push(cite(s.languages));
   lines.push("## Tech Stack");
   if (ctx.languages.length > 0) {
     lines.push(`- Languages: ${ctx.languages.join(", ")}`);
@@ -20468,6 +20510,7 @@ function formatForCursor(ctx, _config) {
     lines.push(`- Frameworks: ${ctx.frameworks.join(", ")}`);
   }
   lines.push("");
+  lines.push(cite(s.commands));
   lines.push("## Commands");
   lines.push(`- Install: \`${ctx.commands.install}\``);
   lines.push(`- Dev: \`${ctx.commands.dev}\``);
@@ -20488,11 +20531,13 @@ function formatForCursor(ctx, _config) {
   return lines.join("\n");
 }
 function formatForCopilot(ctx, _config) {
+  const s = ctx.sources || defaultSources();
   const lines = [];
   lines.push("# Copilot Instructions");
   lines.push("");
   lines.push(`This is ${ctx.name}, a ${ctx.ecosystem} project.`);
   lines.push("");
+  lines.push(cite(s.ecosystem));
   lines.push("## Project Info");
   lines.push(`- Type: ${ctx.projectType}`);
   lines.push(`- Stack: ${ctx.frameworks.join(", ") || ctx.ecosystem}`);
@@ -20502,12 +20547,14 @@ function formatForCopilot(ctx, _config) {
   lines.push("- Match existing code patterns");
   lines.push("- Keep code clean and readable");
   lines.push("");
+  lines.push(cite(s.commands));
   lines.push("## Commands");
   lines.push(`- Test: \`${ctx.commands.test}\``);
   lines.push(`- Build: \`${ctx.commands.build}\``);
   return lines.join("\n");
 }
 function formatForWindsurf(ctx, _config) {
+  const s = ctx.sources || defaultSources();
   const lines = [];
   lines.push("---");
   lines.push(`description: prjct context for ${ctx.name}`);
@@ -20518,12 +20565,14 @@ function formatForWindsurf(ctx, _config) {
   lines.push("");
   lines.push(`${ctx.projectType} project using ${ctx.ecosystem}.`);
   lines.push("");
+  lines.push(cite(s.languages));
   lines.push("## Stack");
   lines.push(`- ${ctx.languages.join(", ")}`);
   if (ctx.frameworks.length > 0) {
     lines.push(`- ${ctx.frameworks.join(", ")}`);
   }
   lines.push("");
+  lines.push(cite(s.commands));
   lines.push("## Commands");
   lines.push("```bash");
   lines.push(`# Install`);
@@ -20597,6 +20646,7 @@ function getFormatter(toolId) {
 var init_formatters = __esm({
   "core/ai-tools/formatters.ts"() {
     "use strict";
+    init_citations();
     __name(formatForClaude, "formatForClaude");
     __name(formatForCursor, "formatForCursor");
     __name(formatForCopilot, "formatForCopilot");
@@ -20811,6 +20861,7 @@ var init_context_generator = __esm({
   "core/services/context-generator.ts"() {
     "use strict";
     init_path_manager();
+    init_citations();
     init_date_helper();
     init_preserve_sections();
     init_nested_context_resolver();
@@ -20846,10 +20897,10 @@ var init_context_generator = __esm({
       /**
        * Generate all context files in parallel
        */
-      async generate(git, stats, commands, agents) {
+      async generate(git, stats, commands, agents, sources) {
         const contextPath = path43.join(this.config.globalPath, "context");
         await Promise.all([
-          this.generateClaudeMd(contextPath, git, stats, commands, agents),
+          this.generateClaudeMd(contextPath, git, stats, commands, agents, sources),
           this.generateNowMd(contextPath),
           this.generateNextMd(contextPath),
           this.generateIdeasMd(contextPath),
@@ -20869,9 +20920,10 @@ var init_context_generator = __esm({
       /**
        * Generate CLAUDE.md - main context file for AI agents
        */
-      async generateClaudeMd(contextPath, git, stats, commands, agents) {
+      async generateClaudeMd(contextPath, git, stats, commands, agents, sources) {
         const workflowAgents = agents.filter((a) => a.type === "workflow").map((a) => a.name);
         const domainAgents = agents.filter((a) => a.type === "domain").map((a) => a.name);
+        const s = sources || defaultSources();
         const content = `# ${stats.name} - Project Rules
 <!-- projectId: ${this.config.projectId} -->
 <!-- Generated: ${date_helper_default.getTimestamp()} -->
@@ -20879,11 +20931,13 @@ var init_context_generator = __esm({
 
 ## THIS PROJECT (${stats.ecosystem})
 
+${cite(s.ecosystem)}
 **Type:** ${stats.projectType}
 **Path:** ${this.config.projectPath}
 
 ### Commands (USE THESE, NOT OTHERS)
 
+${cite(s.commands)}
 | Action | Command |
 |--------|---------|
 | Install dependencies | \`${commands.install}\` |
@@ -20895,7 +20949,9 @@ var init_context_generator = __esm({
 
 ### Code Conventions
 
+${cite(s.languages)}
 - **Languages**: ${stats.languages.join(", ") || "Not detected"}
+${cite(s.frameworks)}
 - **Frameworks**: ${stats.frameworks.join(", ") || "Not detected"}
 
 ---
@@ -20923,6 +20979,7 @@ p. sync \u2192 p. task "desc" \u2192 [work] \u2192 p. done \u2192 p. ship
 
 ## PROJECT STATE
 
+${cite(s.name)}
 | Field | Value |
 |-------|-------|
 | Name | ${stats.name} |
@@ -21637,6 +21694,7 @@ var init_sync_service = __esm({
     init_config_manager();
     init_path_manager();
     init_metrics_storage();
+    init_citations();
     init_date_helper();
     init_context_generator();
     init_local_state_generator();
@@ -21704,7 +21762,8 @@ var init_sync_service = __esm({
           await ensureDirsPromise;
           const agents = await this.generateAgents(stack, stats);
           const skills = this.configureSkills(agents);
-          const contextFiles = await this.generateContextFiles(git, stats, commands, agents);
+          const sources = this.buildSources(stats, commands);
+          const contextFiles = await this.generateContextFiles(git, stats, commands, agents, sources);
           const projectContext = {
             projectId: this.projectId,
             name: stats.name,
@@ -21722,7 +21781,8 @@ var init_sync_service = __esm({
             agents: {
               workflow: agents.filter((a) => a.type === "workflow").map((a) => a.name),
               domain: agents.filter((a) => a.type === "domain").map((a) => a.name)
-            }
+            },
+            sources
           };
           const aiToolResults = await generateAIToolContexts(
             projectContext,
@@ -21975,6 +22035,42 @@ var init_sync_service = __esm({
         return commands;
       }
       // ==========================================================================
+      // SOURCE CITATIONS
+      // ==========================================================================
+      buildSources(stats, commands) {
+        const sources = defaultSources();
+        const ecosystemFiles = {
+          JavaScript: "package.json",
+          Rust: "Cargo.toml",
+          Go: "go.mod",
+          Python: "pyproject.toml"
+        };
+        const ecosystemFile = ecosystemFiles[stats.ecosystem] || "filesystem";
+        const detected = /* @__PURE__ */ __name((file) => ({ file, type: "detected" }), "detected");
+        const inferred = /* @__PURE__ */ __name((file) => ({ file, type: "inferred" }), "inferred");
+        sources.ecosystem = detected(ecosystemFile);
+        sources.name = detected(ecosystemFile);
+        sources.version = detected(ecosystemFile);
+        sources.languages = detected(ecosystemFile);
+        sources.frameworks = detected(ecosystemFile);
+        if (commands.install.startsWith("bun")) {
+          sources.commands = detected("bun.lockb");
+        } else if (commands.install.startsWith("pnpm")) {
+          sources.commands = detected("pnpm-lock.yaml");
+        } else if (commands.install === "yarn") {
+          sources.commands = detected("yarn.lock");
+        } else if (commands.install.startsWith("cargo")) {
+          sources.commands = detected("Cargo.toml");
+        } else if (commands.install.startsWith("go")) {
+          sources.commands = detected("go.mod");
+        } else {
+          sources.commands = detected("package.json");
+        }
+        sources.projectType = inferred("file count + frameworks");
+        sources.git = detected("git");
+        return sources;
+      }
+      // ==========================================================================
       // STACK DETECTION
       // ==========================================================================
       async detectStack() {
@@ -22144,13 +22240,19 @@ You are the ${name} expert for this project. Apply best practices for the detect
       // ==========================================================================
       // CONTEXT FILE GENERATION
       // ==========================================================================
-      async generateContextFiles(git, stats, commands, agents) {
+      async generateContextFiles(git, stats, commands, agents, sources) {
         const generator = new ContextFileGenerator({
           projectId: this.projectId,
           projectPath: this.projectPath,
           globalPath: this.globalPath
         });
-        return generator.generate({ branch: git.branch, commits: git.commits }, stats, commands, agents);
+        return generator.generate(
+          { branch: git.branch, commits: git.commits },
+          stats,
+          commands,
+          agents,
+          sources
+        );
       }
       // ==========================================================================
       // PROJECT.JSON UPDATE
@@ -27817,7 +27919,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "prjct-cli",
-      version: "1.4.0",
+      version: "1.5.0",
       description: "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
       main: "core/index.ts",
       bin: {
@@ -27943,29 +28045,36 @@ async function main() {
   try {
     const cmd = commandRegistry.getByName(commandName);
     if (!cmd) {
-      console.error(`Unknown command: ${commandName}`);
-      console.error(`
-Use 'prjct --help' to see available commands.`);
+      const suggestion = findClosestCommand(commandName);
+      const hint = suggestion ? `Did you mean 'prjct ${suggestion}'? Run 'prjct --help' for all commands` : "Run 'prjct --help' to see available commands";
+      output_default.failWithHint(
+        getError("UNKNOWN_COMMAND", { message: `Unknown command: ${commandName}`, hint })
+      );
       output_default.end();
       process.exit(1);
     }
     if (cmd.deprecated) {
-      console.error(`Command '${commandName}' is deprecated.`);
-      if (cmd.replacedBy) {
-        console.error(`Use 'prjct ${cmd.replacedBy}' instead.`);
-      }
+      const hint = cmd.replacedBy ? `Use 'prjct ${cmd.replacedBy}' instead` : "Run 'prjct --help' to see available commands";
+      output_default.failWithHint({ message: `Command '${commandName}' is deprecated`, hint });
       output_default.end();
       process.exit(1);
     }
     if (!cmd.implemented) {
-      console.error(`Command '${commandName}' exists but is not yet implemented.`);
-      console.error(`Check the roadmap or contribute: https://github.com/jlopezlira/prjct-cli`);
-      console.error(`
-Use 'prjct --help' to see available commands.`);
+      output_default.failWithHint({
+        message: `Command '${commandName}' is not yet implemented`,
+        hint: "Run 'prjct --help' to see available commands",
+        docs: "https://github.com/jlopezlira/prjct-cli"
+      });
       output_default.end();
       process.exit(1);
     }
     const { parsedArgs, options } = parseCommandArgs(cmd, rawArgs);
+    const paramError = validateCommandParams(cmd, parsedArgs);
+    if (paramError) {
+      output_default.failWithHint(paramError);
+      output_default.end();
+      process.exit(1);
+    }
     let projectId = null;
     const commandStartTime = Date.now();
     try {
@@ -28056,6 +28165,46 @@ Use 'prjct --help' to see available commands.`);
     process.exit(1);
   }
 }
+function validateCommandParams(cmd, parsedArgs) {
+  if (!cmd.params) return null;
+  const requiredParams = cmd.params.match(/<[^>]+>/g);
+  if (!requiredParams || requiredParams.length === 0) return null;
+  if (parsedArgs.length < requiredParams.length) {
+    const paramNames = requiredParams.map((p) => p.slice(1, -1)).join(", ");
+    const usage = cmd.usage.terminal || `prjct ${cmd.name} ${cmd.params}`;
+    return getError("MISSING_PARAM", {
+      message: `Missing required parameter: ${paramNames}`,
+      hint: `Usage: ${usage}`
+    });
+  }
+  return null;
+}
+function findClosestCommand(input) {
+  const allNames = commandRegistry.getAll().map((c) => c.name);
+  let best = null;
+  let bestDist = Infinity;
+  for (const name of allNames) {
+    const dist = editDistance(input.toLowerCase(), name.toLowerCase());
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = name;
+    }
+  }
+  return bestDist <= 2 ? best : null;
+}
+function editDistance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
 function parseCommandArgs(_cmd, rawArgs) {
   const parsedArgs = [];
   const options = {};
@@ -28192,8 +28341,12 @@ var init_core = __esm({
     init_ai_provider();
     init_config_manager();
     init_session_tracker();
+    init_error_messages();
     init_output();
     __name(main, "main");
+    __name(validateCommandParams, "validateCommandParams");
+    __name(findClosestCommand, "findClosestCommand");
+    __name(editDistance, "editDistance");
     __name(parseCommandArgs, "parseCommandArgs");
     __name(displayVersion, "displayVersion");
     __name(displayHelp, "displayHelp");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
   "main": "core/index.ts",
   "bin": {