fix(person): Support name lookup and id: prefix syntax (#13)

## Summary
- Fix missing Content-Type header for POST requests without body
- Add name-based person lookup via search API (exact then partial
matching)
- Require explicit `id:xxx` prefix for ID lookups to eliminate ambiguity
- Support email addresses for direct lookup
- Comprehensive help text and error hints for AI agent usability

## Test plan
- `bob person Ernesto` → name search
- `bob person id:12345` → direct ID lookup
- `bob person user@co.com` → direct email lookup
- All 27 existing tests pass

🤖 Generated with Claude Code

---------

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

Author: gnapse

src/commands/people.ts

@@ -183,12 +183,75 @@ async function listPeople(query: string | undefined, options: PeopleOptions): Pr
     outputList(people, options, 'person', renderPersonRow)
 }
 
-async function viewPerson(id: string, options: OutputOptions): Promise<void> {
-    if (!id) {
-        throw new Error(formatError('MISSING_ID', 'Person id is required.'))
+function isIdRef(ref: string): boolean {
+    return ref.startsWith('id:')
+}
+
+function removeIdPrefix(ref: string): string {
+    return ref.slice(3)
+}
+
+function looksLikeRawId(ref: string): boolean {
+    if (ref.includes(' ')) return false
+    return /^\d+$/.test(ref)
+}
+
+async function fetchPersonByIdentifier(id: string): Promise<Record<string, unknown>> {
+    const response = await apiPost(`/people/${id}`, {})
+    return extractPerson(response)
+}
+
+async function resolvePersonRef(ref: string): Promise<Record<string, unknown>> {
+    if (isIdRef(ref)) {
+        return fetchPersonByIdentifier(removeIdPrefix(ref))
+    }
+
+    // HiBob API accepts email as an identifier in /people/{identifier}
+    if (ref.includes('@')) {
+        return fetchPersonByIdentifier(ref)
+    }
+
+    if (looksLikeRawId(ref)) {
+        return fetchPersonByIdentifier(ref)
     }
-    const response = await apiPost(`/people/${id}`)
-    const person = extractPerson(response)
+
+    const response = await apiPost('/people/search', {})
+    const people = extractPeopleList(response).filter((p) => isActive(p) !== false)
+    const lower = ref.toLowerCase()
+
+    const exact = people.find((p) => getDisplayName(p).toLowerCase() === lower)
+    if (exact) {
+        const id = exact.id
+        if (typeof id === 'string' && id) return fetchPersonByIdentifier(id)
+        return exact
+    }
+
+    const partial = people.filter((p) => getDisplayName(p).toLowerCase().includes(lower))
+    if (partial.length === 1) {
+        const id = partial[0].id
+        if (typeof id === 'string' && id) return fetchPersonByIdentifier(id)
+        return partial[0]
+    }
+    if (partial.length > 1) {
+        throw new Error(
+            formatError(
+                'AMBIGUOUS_PERSON',
+                `Multiple people match "${ref}":`,
+                partial.slice(0, 5).map((p) => `"${getDisplayName(p)}" (id:${p.id})`),
+            ),
+        )
+    }
+
+    throw new Error(formatError('PERSON_NOT_FOUND', `Person "${ref}" not found.`))
+}
+
+async function viewPerson(ref: string, options: OutputOptions): Promise<void> {
+    if (!ref) {
+        throw new Error(
+            formatError('MISSING_REF', 'Person ref is required (name, email, or id:xxx).'),
+        )
+    }
+    const person = await resolvePersonRef(ref)
     outputItem(person, options, 'person', renderPersonView)
 }
 
@@ -207,10 +270,20 @@ export function registerPeopleCommand(program: Command): void {
     program
         .command('person')
         .description('View a single employee')
-        .argument('<id>', 'Employee id')
+        .argument('<ref>', 'Name, email, or id:xxx')
         .option('--json', 'JSON output (essential fields)')
         .option('--ndjson', 'NDJSON output (essential fields)')
         .option('--full', 'Include all fields in JSON output')
+        .addHelpText(
+            'after',
+            `
+Ref formats:
+  id:xxx       Direct lookup by HiBob employee ID (exact, fastest)
+  user@co.com  Direct lookup by email address
+  "Jane Doe"   Name search (exact match preferred, partial if unambiguous)
+
+Use "bob people" to list employees and find id:xxx values.`,
+        )
         .action((id: string, options: OutputOptions) => viewPerson(id, options))
 
     people.addHelpText(

src/lib/skills/content.ts

@@ -10,7 +10,7 @@ Use this skill when the user wants to query HiBob HR data.
 
 - \`bob people\` - List employees
 - \`bob people "john"\` - Search employees by name (local filter)
-- \`bob person <id>\` - View a single employee
+- \`bob person <ref>\` - View a single employee (name, email, or id:xxx)
 - \`bob whosout\` - Who is out of office
 - \`bob outtoday\` - Who is out today
 - \`bob skill list\` - List supported agents
@@ -27,7 +27,8 @@ All list commands support:
 \`\`\`bash
 bob people --json
 bob people "Ava" --department "Engineering"
-bob person 12345
+bob person "Jane Doe"
+bob person id:12345
 bob whosout --from 2024-01-15 --to 2024-01-20
 bob outtoday --date 2024-01-15
 \`\`\`