## TL;DR
Point the agent's parser at a TypeScript-aware AST with decorators enabled. Generic JavaScript parsers die on decorator syntax because it is still experimental syntax outside the base grammar.
Fix: parse with the TypeScript compiler API (or a parser with the TypeScript and decorators plugins) and retry extraction.

## The error
```text
agent's ast parser failed on typescript decorators
```

## Steps
1. Find which parser the agent uses and the exact error line. Decorator failures point at the line with the at-sign syntax, e.g. at-Injectable() above a class.
   Expected: the failing file and the failing construct are identified.
2. Check the TypeScript version the repo uses and whether the parser supports it: run `npx tsc --version` and compare with the parser's supported range.
   Expected: you know whether the parser is simply too old or missing a plugin.
3. If the agent uses a generic parser (e.g. a Babel or ESTree-based one), switch decorator handling on: enable the TypeScript syntax plugin plus decorators support, matching the repo's tsconfig (experimentalDecorators and the decorators version it uses).
   Expected: the previously failing file parses without errors.
4. For the most robust path, switch extraction to the TypeScript compiler API directly (ts.createSourceFile) which always understands the repo's own syntax.
   Expected: all decorated classes, properties, and parameters extract cleanly.
5. Re-run doc generation over the decorated files.
   Expected: reference docs now include the decorated classes with no parser errors.

## Use this when
- the docs agent's AST parser throws on files using decorators
- doc generation skips or crashes on at-Component, at-Injectable, at-Module style code
- switching a repo to TypeScript broke a previously working doc pipeline

## Not for this skill when
- the parser fails on plain TypeScript with no decorators (different syntax issue)
- decorators are the legacy experimental kind vs the new standard kind and you need semantics, not parsing (that is a type-checker question)
- the docs are hand-written markdown, no AST extraction involved

## Variant phrasings
- parser fails on at-decorator syntax in TypeScript files
- doc generator crashes on decorated classes
- AST extraction error on experimental decorators
- typescript compiler API needed for decorator parsing

## Why it happens
Decorators are not part of the core JavaScript grammar that generic parsers implement. TypeScript also has two decorator flavors (legacy experimental and the newer standard), and a parser configured for one rejects the other. A docs agent using a plain JS parser therefore fails at the first at-sign.

## Edge cases
- Mixed repos where some files use legacy decorators and others use standard decorators: the parser must accept both, or the agent should use the TS compiler API which follows tsconfig per project.
- Decorator factories with arguments: make sure extraction records the decorator name and arguments, not just the class.
- .d.ts declaration files: these use declare syntax that also needs the TS parser, so route them through the same path.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_-HX14fJ7fMXzZlfMyjQpvg