Part 3: Your First Annotation

With configuration in place, you now annotate one TypeScript file and see the system detect it.

3.1 File opt-in

Every file that the scanner should process needs a file opt-in marker. For the libar-generic preset, this is:

/** @libar-docs */

This must be a standalone JSDoc comment at the top of the file. Without it, the file is invisible to the scanner.

3.2 Create your first annotated source

Create src/sample-sources/user-service.ts with just the essential tags:

/** @libar-docs */

/**
 * @libar-docs-pattern UserService
 * @libar-docs-status active
 * @libar-docs-core
 * @libar-docs-brief Core user lifecycle management service
 *
 * ## UserService - User Lifecycle Management
 *
 * Manages user lifecycle — registration, lookup, and deactivation.
 *
 * ### When to Use
 *
 * - When registering new users
 * - When looking up user information
 * - When deactivating user accounts
 */

export class UserService {
  private users = new Map<string, { id: string; email: string; active: boolean }>();

  register(email: string): string {
    const id = crypto.randomUUID();
    this.users.set(id, { id, email, active: true });
    return id;
  }

  findById(id: string): { id: string; email: string; active: boolean } | null {
    return this.users.get(id) ?? null;
  }

  deactivate(id: string): boolean {
    const user = this.users.get(id);
    if (!user) return false;
    user.active = false;
    return true;
  }
}

Four tags is all you need to get started:

• @libar-docs-pattern UserService — names this pattern (required)
• @libar-docs-status active — FSM status: roadmap -> active -> completed, or deferred
• @libar-docs-core — category assignment (flag tag — no value needed)
• @libar-docs-brief — short description for summary tables

3.3 See it detected

npm run process:overview

=== PROGRESS ===
1 patterns (0 completed, 1 active, 0 planned) = 0%

What just happened: The scanner found user-service.ts, detected the @libar-docs opt-in marker, and extracted the UserService pattern with status active in the core category. One file, one pattern — and it is already queryable.

Verify which files the scanner found:

npm run process:sources

{
  "success": true,
  "data": {
    "types": [
      {
        "type": "TypeScript (annotated)",
        "count": 1,
        "locationPattern": "src/sample-sources/**/*.ts",
        "files": [
          "src/sample-sources/user-service.ts"
        ]
      }
    ],
    "totalFiles": 1
  },
  "metadata": {
    "timestamp": "2026-02-21T07:59:56.192Z",
    "patternCount": 1
  }
}

Recap: Part 3

You created one annotated file and proved the scanner detects it. The minimum viable annotation is:

1. @libar-docs — file opt-in marker
2. @libar-docs-pattern Name — names the pattern
3. @libar-docs-status — FSM status
4. A category flag (@libar-docs-core, -api, or -infra)

Next, you will add tags that make the documentation richer.

---