agent-readable-ts 0.1.4 → 0.1.5

package/README.md

@@ -1,305 +1,23 @@
 # agent-readable-ts
 
-Coding agents hallucinate a library's API — inventing methods, using stale signatures, or misusing real methods because the correct usage rules (lifecycle order, preconditions, anti-patterns) are not visible from the API surface alone.
+[![CI](https://github.com/zydo/agent-readable-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/zydo/agent-readable-ts/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/agent-readable-ts.svg)](https://www.npmjs.com/package/agent-readable-ts)
 
-`agent-readable-ts` lets a library author attach those rules next to a class, object, or function. A package-level function `agentHelp(target)` returns curated, agent-oriented Markdown: the real public runtime surface that can be discovered safely, plus any author-supplied behavioral rules. An agent that calls `agentHelp(target)` before writing code against the target sees the real callable surface and the right usage rules.
+`agent-readable-ts` helps coding agents inspect the live public surface of a
+TypeScript or JavaScript API before they write code against it.
 
-> **For coding agents:** Install the agent skill to have this run automatically before coding against unfamiliar packages:
-> ```sh
-> npx skills add zydo/skills --skill agent-readable
-> ```
+Library authors can add agent-oriented usage rules next to a class, object, or
+function. Consumers call `agentHelp(target)` or the `agent-readable-ts` CLI to get
+compact Markdown with the real callable surface plus any author-supplied
+behavioral notes.
 
-**Token efficiency.** When an agent hallucinates an API, the resulting code fails — and each failed attempt triggers a retry cycle that burns tokens without making progress. `agent-readable-ts` generates compact, precise, accurate descriptions of publicly exposed interfaces (verified by runtime introspection on live packages). Calling `npx agent-readable-ts <package>` on unfamiliar packages and classes *before* writing code surfaces the real API upfront, preventing that waste.
-
-## Other languages
-
-- **Python:** [agent-readable](https://github.com/zydo/agent-readable) — same idea for Python packages and classes.
-
-## Install
-
-```sh
-npm install agent-readable-ts
-```
-
-## CLI
-
-The package includes a CLI for generating documentation from the command line. It works with local files **and installed npm packages**.
-
-```sh
-npx agent-readable-ts commander           # list all exports
-npx agent-readable-ts commander:Command   # document a specific export
-npx agent-readable-ts ./src/widget.ts:Widget   # a local TypeScript file
-```
-
-### Usage
-
-```sh
-agent-readable-ts [--install] <package-name>[:<export-name>]
-agent-readable-ts <module-path>[:<export-name>]
-```
-
-- **`package-name`** — any installed npm package (e.g. `commander`, `pino`, `@scope/package`)
-- **`module-path`** — a file path (`.js`, `.mjs`, or `.ts`) relative to the current directory
-- **`export-name`** — the named export to document (use dots for nested access, e.g. `Things.Helper`)
-- **`--install`** — allow fetching a package on demand when it is not installed locally (see [Security](#security))
-
-If no export name is given for a **package**, all exports are listed. If no export name is given for a **file**, the module namespace object is documented.
-
-> `.ts` files require `tsx` to be installed. It is included as a devDependency, and `npx` resolves it automatically.
-
-### Examples
-
-List all exports from an installed package:
-
-```sh
-npm install commander
-npx agent-readable-ts commander
-```
-
-Output:
-
-```markdown
-# commander
-
-## Exports
-
-- `CommanderError` class
-- `InvalidArgumentError` class
-- `Argument` class
-- `Option` class
-- `Help` class
-- `Command` class
-- `createCommand(name: string): Command` function
-- `createOption(flags: string, description: string): Option` function
-- `createArgument(name: string, description: string): Argument` function
-- `program` object
-```
-
-Document a specific export with full type signatures:
+To let your coding agent automatically call `agentHelp()` before using an
+unfamiliar API, install the companion skill:
 
 ```sh
-npx agent-readable-ts commander:Command
-```
-
-Output:
-
-```markdown
-# Command
-
-## Public API
-
-- `action(fn: (this: this, ...args: any[]) => void | Promise<void>): this` method
-- `addArgument(arg: Argument): this` method
-- `addCommand(cmd: Command, opts: CommandOptions): this` method
-- `addOption(option: Option): this` method
-- `alias(): string` method
-- `argument(name: string, description: string, defaultValue: unknown): this` method
-- `command(nameAndArgs: string, description: string, opts: ExecutableCommandOptions): this` method
-- `description(): string` method
-- `error(message: string, errorOptions: ErrorOptions): never` method
-- `hook(event: HookEvent, listener: (...args: any[]) => void | Promise<void>): this` method
-- `option(flags: string, description: string, defaultValue: unknown): this` method
-- `parse(argv: readonly string[], parseOptions: ParseOptions): this` method
-- `parseAsync(argv: readonly string[], parseOptions: ParseOptions): Promise<this>` method
-- `requiredOption(flags: string, description: string, defaultValue: unknown): this` method
-- `version(str: string, flags: string, description: string): this` method
-- ... (80+ methods total)
-
-## Agent usage rules
-
-- Prefer the public API listed above.
-- Do not use private, protected, underscored, or internal members.
-- Do not invent unsupported behavior.
-- If usage is ambiguous, prefer the simplest documented usage pattern.
-```
-
-Document a local file:
-
-```sh
-npx agent-readable-ts ./src/widget.ts:Widget    # a class export
-npx agent-readable-ts ./src/util.ts:connect     # a function export
-npx agent-readable-ts ./dist/api.js:fetch       # a .js file with adjacent api.d.ts
-```
-
-### Security
-
-To document a package, the CLI imports it, which executes the package's top-level code — only point it at packages you trust to run on your machine.
-
-When a package is not resolvable from the current project, the CLI can fetch it on demand with `npm install`. This never happens silently:
-
-- **Opt-in only.** On-demand fetching requires the `--install` flag. Without it, the CLI exits with an error telling you how to install the package yourself.
-- **Isolated cache.** Fetched packages go into `~/.cache/agent-readable-ts` (override with the `AGENT_READABLE_CACHE` environment variable), never into your project's `node_modules` or `package.json`.
-- **No lifecycle scripts.** The install runs with `--ignore-scripts`, so `preinstall`/`postinstall` scripts of fetched packages are never executed.
-- **No re-fetching.** Packages already present in the cache are loaded from disk without touching the network, and never require `--install` again.
-
-Packages already installed in your project are always loaded directly — no network access, no cache.
-
-## Two protocols
-
-| Protocol       | Role              | Output behavior                                  |
-| -------------- | ----------------- | ------------------------------------------------ |
-| `agentHelp()`  | Full replacement  | Returned Markdown is used verbatim               |
-| `agentNotes()` | Additive guidance | Notes are appended after auto-generated API docs |
-
-### `agentHelp()` — Full replacement
-
-If a target implements `agentHelp()`, the returned string **is** the output verbatim. No auto-generated sections are added.
-
-```ts
-import { AgentHelper, agentHelp } from "agent-readable-ts";
-
-class RateLimiter implements AgentHelper {
-  agentHelp(): string {
-    return `# RateLimiter
-
-## Usage
-
-- Create with \`new RateLimiter(maxRequests)\`.
-- Call \`acquire()\` before making a request.
-- Call \`release()\` after the request completes.
-
-## Limits
-
-- Default max is 100 concurrent requests.
-- Exceeding the limit blocks until a slot opens.
-`;
-  }
-}
-
-console.log(agentHelp(new RateLimiter()));
-```
-
-Output:
-
-```markdown
-# RateLimiter
-
-## Usage
-
-- Create with `new RateLimiter(maxRequests)`.
-- Call `acquire()` before making a request.
-- Call `release()` after the request completes.
-
-## Limits
-
-- Default max is 100 concurrent requests.
-- Exceeding the limit blocks until a slot opens.
-```
-
-If the target also defines `agentNotes()`, a warning is written to stderr and the notes are dropped.
-
-### `agentNotes()` — Additive guidance
-
-Define `agentNotes()` on any class to append usage rules to the auto-generated documentation. Notes accumulate across the inheritance chain in parent-to-child order.
-
-```ts
-import { AgentNoter, agentHelp } from "agent-readable-ts";
-
-class Sensor {
-  calibrate(offset: number): void {}
-  read(): number {
-    return 0;
-  }
-
-  agentNotes(): string {
-    return `
-## Do
-
-- Call \`calibrate()\` once during setup, before \`read()\`.
-
-## Do not
-
-- Do not call \`read()\` before \`calibrate()\` on first use.
-`;
-  }
-}
-
-console.log(agentHelp(new Sensor()));
-```
-
-### `agentHelp(target)` entry point
-
-The single entry point accepts:
-
-- Class constructors
-- Class instances
-- Plain objects
-- Plain functions
-- Arrow functions
-- Bound method values
-- Callable objects
-
-```ts
-import { agentHelp } from "agent-readable-ts";
-
-agentHelp(MyClass);          // class constructor
-agentHelp(new MyClass());    // class instance
-agentHelp({ a: 1 });        // plain object
-agentHelp(myFunction);       // function
-agentHelp(obj.method.bind(obj)); // bound method
-```
-
-## Examples
-
-### Example 1: Wrapping a class you do not own
-
-```ts
-import { agentHelp } from "agent-readable-ts";
-
-class Client {
-  connect(url: string): void {}
-  query(sql: string): unknown {
-    return undefined;
-  }
-}
-
-class DocumentedClient extends Client {
-  agentNotes(): string {
-    return `
-## Do
-
-- Call \`connect()\` before \`query()\`.
-
-## Do not
-
-- Do not pass untrusted SQL directly to \`query()\`.
-`;
-  }
-}
-
-console.log(agentHelp(new DocumentedClient()));
+npx skills add zydo/skills --skill agent-readable
 ```
 
-Output:
-
-```markdown
-# DocumentedClient
-
-## Public API
-
-- `connect(url)` method
-- `query(sql)` method
-
-## Agent usage rules
-
-- Prefer the public API listed above.
-- Do not use private, protected, underscored, or internal members.
-- Do not invent unsupported behavior.
-- If usage is ambiguous, prefer the simplest documented usage pattern.
-
-## Notes from DocumentedClient
-
-## Do
-
-- Call `connect()` before `query()`.
-
-## Do not
-
-- Do not pass untrusted SQL directly to `query()`.
-```
-
-### Example 2: Inheritance with accumulated notes
-
 ```ts
 import { agentHelp } from "agent-readable-ts";
 
@@ -310,255 +28,41 @@ class Sensor {
   }
 
   agentNotes(): string {
-    return `
-## Do
-
-- Call \`calibrate()\` once during setup, before \`read()\`.
-
-## Do not
-
-- Do not call \`read()\` before \`calibrate()\` on first use.
-`;
-  }
-}
-
-class CalibratedSensor extends Sensor {
-  reset(): void {}
-
-  override agentNotes(): string {
-    return `
-## Do
-
-- Use \`reset()\` only when recalibration is required.
-
-## Do not
-
-- Do not call \`reset()\` in the hot read path.
-`;
-  }
-}
-
-console.log(agentHelp(new CalibratedSensor()));
-```
-
-Output:
-
-```markdown
-# CalibratedSensor
-
-## Public API
-
-- `calibrate(offset)` method
-- `read()` method
-- `reset()` method
-
-## Agent usage rules
-
-- Prefer the public API listed above.
-- Do not use private, protected, underscored, or internal members.
-- Do not invent unsupported behavior.
-- If usage is ambiguous, prefer the simplest documented usage pattern.
-
-## Notes from Sensor
-
-## Do
-
-- Call `calibrate()` once during setup, before `read()`.
-
-## Do not
-
-- Do not call `read()` before `calibrate()` on first use.
-
-## Notes from CalibratedSensor (extends Sensor; if notes conflict, these take precedence)
-
-## Do
-
-- Use `reset()` only when recalibration is required.
-
-## Do not
-
-- Do not call `reset()` in the hot read path.
-```
-
-### Example 3: Full control via `agentHelp()`
-
-```ts
-import { agentHelp } from "agent-readable-ts";
-
-class RateLimiter {
-  agentHelp(): string {
-    return `# RateLimiter
-
-## Usage
-
-- Create with \`new RateLimiter(maxRequests)\`.
-- Call \`acquire()\` before making a request.
-- Call \`release()\` after the request completes.
-
-## Limits
-
-- Default max is 100 concurrent requests.
-- Exceeding the limit blocks until a slot opens.
-`;
-  }
-  agentNotes(): string {
-    return "This is ignored because agentHelp() owns the full output.";
+    return "- Call `calibrate()` once during setup, before `read()`.";
   }
 }
 
-console.log(agentHelp(new RateLimiter()));
-```
-
-Output:
-
-```markdown
-# RateLimiter
-
-## Usage
-
-- Create with `new RateLimiter(maxRequests)`.
-- Call `acquire()` before making a request.
-- Call `release()` after the request completes.
-
-## Limits
-
-- Default max is 100 concurrent requests.
-- Exceeding the limit blocks until a slot opens.
-```
-
-A warning is written to stderr noting that `agentNotes()` is ignored.
-
-### Example 4: Any class, no setup
-
-```ts
-import { agentHelp } from "agent-readable-ts";
-
-class Cache {
-  get(key: string): unknown {
-    return undefined;
-  }
-  set(key: string, value: unknown): void {}
-  clear(): void {}
-}
-
-console.log(agentHelp(new Cache()));
-```
-
-Output:
-
-```markdown
-# Cache
-
-## Public API
-
-- `clear()` method
-- `get(key)` method
-- `set(key, value)` method
-
-## Agent usage rules
-
-- Prefer the public API listed above.
-- Do not use private, protected, underscored, or internal members.
-- Do not invent unsupported behavior.
-- If usage is ambiguous, prefer the simplest documented usage pattern.
-```
-
-### Example 5: Functions and bound methods
-
-```ts
-import { agentHelp } from "agent-readable-ts";
-
-function connect(host: string, port: number): void {}
-
-class Runner {
-  execute(command: string): number {
-    return 0;
-  }
-}
-
-const runner = new Runner();
-
-console.log(agentHelp(connect));
-console.log(agentHelp(runner.execute.bind(runner)));
+console.log(agentHelp(new Sensor()));
 ```
 
-Output for `connect`:
-
-````markdown
-# connect
-
-## Signature
+## Install
 
-```ts
-connect(host, port)
+```sh
+npm install agent-readable-ts
 ```
 
-## Agent usage rules
-
-- Call this function according to the signature above.
-- Do not invent unsupported parameters, return values, side effects, or lifecycle behavior.
-- Do not use private, underscored, or internal implementation details.
-- If usage is ambiguous, prefer the simplest documented usage pattern.
-````
-
-Output for the bound method:
+For one-off CLI use:
 
-````markdown
-# execute
-
-## Signature
-
-```ts
-execute(arg0)
+```sh
+npx agent-readable-ts commander
+npm exec -- agent-readable-ts commander:Command
+pnpm dlx agent-readable-ts ./src/widget.ts:Widget
 ```
 
-## Agent usage rules
-
-- Call this function according to the signature above.
-- Do not invent unsupported parameters, return values, side effects, or lifecycle behavior.
-- Do not use private, underscored, or internal implementation details.
-- If usage is ambiguous, prefer the simplest documented usage pattern.
-````
-
-## Warning output
+See [Getting Started](docs/getting-started.md) for full install and CLI usage.
 
-By default, advisory warnings are written to `process.stderr`. You can redirect or silence them:
-
-```ts
-import { setWarnOutput, getWarnOutput } from "agent-readable-ts";
-
-// Redirect to a custom sink
-setWarnOutput((chunk: string) => {
-  console.log("[WARN]", chunk.trim());
-});
-
-// Or use an object with a write method
-setWarnOutput({ write(chunk: string) { /* handle */ } });
-
-// Silence warnings
-setWarnOutput(null);
-
-// Restore default
-setWarnOutput(process.stderr);
-```
+## Documentation
 
-## Limitations in TypeScript
+- [Getting Started](docs/getting-started.md)
+- [Why agent-readable-ts?](docs/why.md)
+- [Examples](docs/examples.md)
+- [Authoring Notes](docs/authoring.md)
+- [FAQ](docs/faq.md)
 
-Runtime JavaScript reflection cannot read TypeScript type annotations, interfaces, overloads, generic parameters, return types, or doc comments. The auto-generated documentation is intentionally conservative:
+## Other Languages
 
-- **Parameter names** are recovered from `Function.prototype.toString()` when possible. For native or bound functions, names fall back to `arg0`, `arg1`, etc. using `Function.length`. Destructured parameters also fall back to `argN`.
-- **Type information** is available in two ways:
-  - **CLI with `.ts` source**: full types are extracted by parsing the source file with the TypeScript compiler API.
-  - **CLI with `.js`/`.mjs`/`.cjs` files**: types are extracted from adjacent `.d.ts`/`.d.mts`/`.d.cts` declaration files if present (covers published packages).
-  - **Library API (`agentHelp()`)**: no type information — only runtime parameter names and arity.
-- **No per-method descriptions.** Authors convey prose through `agentNotes()` or by implementing `agentHelp()`.
-- **Constructors are not invoked** during introspection. Construction guidance belongs in notes.
-- **Instance fields** can only be discovered from an actual instance or plain object, not from a class constructor.
-- **Getters are not invoked** during introspection.
-- **TypeScript `private` and `protected`** are compile-time constructs. The library excludes names starting with `_` but cannot perfectly detect visibility at runtime.
-- **JavaScript `#private` fields and methods** are not reflectable and never appear in output.
-- **Module-level documentation** is not supported.
-- **Dynamic package import or CLI-based introspection** is intentionally omitted.
+- **Python:** [agent-readable](https://github.com/zydo/agent-readable) provides
+  the same idea for Python packages and classes.
 
 ## License
 

package/docs/authoring.md

@@ -0,0 +1,112 @@
+# Authoring Notes
+
+Start with clear public method names and JSDoc. Add `agentNotes()` only when a
+class or object has cross-method rules that are easy to miss.
+
+Use `agentHelp()` rarely, when the auto-generated output is not the right shape
+and you want to provide the full Markdown response yourself.
+
+## `agentNotes()`
+
+Define `agentNotes()` to append usage guidance after the generated public API
+docs.
+
+```ts
+import { AgentNoter } from "agent-readable-ts";
+
+interface Connection {}
+
+class DatabasePool implements AgentNoter {
+  acquire(): Promise<Connection> {
+    throw new Error("not implemented");
+  }
+
+  release(conn: Connection): void {}
+
+  shutdown(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  agentNotes(): string {
+    return `
+## Do
+
+- Always call \`release(conn)\` after every \`acquire()\`, even on error.
+- Call \`shutdown()\` during graceful application teardown.
+
+## Do not
+
+- Do not call \`acquire()\` after \`shutdown()\`.
+- Do not share a \`Connection\` object across async tasks.
+`;
+  }
+}
+```
+
+`agentNotes()` is a good fit for:
+
+- lifecycle and call ordering rules;
+- preconditions and cleanup requirements;
+- sync vs async constraints;
+- streaming vs non-streaming behavior;
+- important do and do-not guidance.
+
+Avoid duplicating obvious method-level information that belongs in names,
+signatures, or JSDoc.
+
+## Inheritance
+
+Notes accumulate across the inheritance chain in parent-to-child order.
+
+Unlike Python, TypeScript does not automatically merge notes from separate
+prototype methods. Implement `agentNotes()` on each class that has its own
+cross-method rules.
+
+## `agentHelp()`
+
+Implement `agentHelp()` for full control over the returned Markdown:
+
+```ts
+import { AgentHelper } from "agent-readable-ts";
+
+class RateLimiter implements AgentHelper {
+  agentHelp(): string {
+    return `# RateLimiter
+
+## Usage
+
+- Create with \`new RateLimiter(maxRequests)\`.
+- Call \`acquire()\` before making a request.
+- Call \`release()\` after the request completes.
+`;
+  }
+}
+```
+
+If both `agentHelp()` and `agentNotes()` are defined on the same target,
+`agentHelp()` wins and `agentNotes()` is ignored. The library emits a warning,
+but authors should treat this as an API design error.
+
+## Warning Output
+
+By default, advisory warnings are written to `process.stderr`. You can redirect
+or silence them:
+
+```ts
+import { getWarnOutput, setWarnOutput } from "agent-readable-ts";
+
+setWarnOutput((chunk: string) => {
+  console.log("[WARN]", chunk.trim());
+});
+
+setWarnOutput({
+  write(chunk: string) {
+    console.log(chunk);
+  },
+});
+
+setWarnOutput(null);
+setWarnOutput(process.stderr);
+```
+
+`getWarnOutput()` returns the current warning sink.

package/docs/examples.md

@@ -0,0 +1,166 @@
+# Examples
+
+## Installed Package
+
+List all exports from an installed package:
+
+```sh
+npm install commander
+npx agent-readable-ts commander
+```
+
+Example output:
+
+```markdown
+# commander
+
+## Exports
+
+- `CommanderError` class
+- `InvalidArgumentError` class
+- `Argument` class
+- `Option` class
+- `Help` class
+- `Command` class
+- `createCommand(name: string): Command` function
+- `createOption(flags: string, description: string): Option` function
+- `createArgument(name: string, description: string): Argument` function
+- `program` object
+```
+
+Document a specific export:
+
+```sh
+npx agent-readable-ts commander:Command
+```
+
+## Local File
+
+```sh
+npx agent-readable-ts ./src/widget.ts:Widget
+npx agent-readable-ts ./src/util.ts:connect
+npx agent-readable-ts ./dist/api.js:fetch
+```
+
+For `.js`, `.mjs`, and `.cjs` files, the CLI can read adjacent `.d.ts`,
+`.d.mts`, and `.d.cts` declaration files when they exist.
+
+## Wrapping a Class You Do Not Own
+
+```ts
+import { agentHelp } from "agent-readable-ts";
+
+class Client {
+  connect(url: string): void {}
+  query(sql: string): unknown {
+    return undefined;
+  }
+}
+
+class DocumentedClient extends Client {
+  agentNotes(): string {
+    return `
+## Do
+
+- Call \`connect()\` before \`query()\`.
+
+## Do not
+
+- Do not pass untrusted SQL directly to \`query()\`.
+`;
+  }
+}
+
+console.log(agentHelp(new DocumentedClient()));
+```
+
+## Inheritance With Accumulated Notes
+
+```ts
+import { agentHelp } from "agent-readable-ts";
+
+class Sensor {
+  calibrate(offset: number): void {}
+  read(): number {
+    return 0;
+  }
+
+  agentNotes(): string {
+    return `
+## Do
+
+- Call \`calibrate()\` once during setup, before \`read()\`.
+
+## Do not
+
+- Do not call \`read()\` before \`calibrate()\` on first use.
+`;
+  }
+}
+
+class CalibratedSensor extends Sensor {
+  reset(): void {}
+
+  override agentNotes(): string {
+    return `
+## Do
+
+- Use \`reset()\` only when recalibration is required.
+
+## Do not
+
+- Do not call \`reset()\` in the hot read path.
+`;
+  }
+}
+
+console.log(agentHelp(new CalibratedSensor()));
+```
+
+Notes are emitted in parent-to-child order. If rules conflict, the child class
+guidance should be treated as more specific.
+
+## Full Control With `agentHelp()`
+
+```ts
+import { agentHelp } from "agent-readable-ts";
+
+class RateLimiter {
+  agentHelp(): string {
+    return `# RateLimiter
+
+## Usage
+
+- Create with \`new RateLimiter(maxRequests)\`.
+- Call \`acquire()\` before making a request.
+- Call \`release()\` after the request completes.
+`;
+  }
+}
+
+console.log(agentHelp(new RateLimiter()));
+```
+
+When `agentHelp()` exists, its returned Markdown is used verbatim.
+
+## Functions and Bound Methods
+
+```ts
+import { agentHelp } from "agent-readable-ts";
+
+function connect(host: string, port: number): void {}
+
+class Runner {
+  execute(command: string): number {
+    return 0;
+  }
+}
+
+const runner = new Runner();
+
+console.log(agentHelp(connect));
+console.log(agentHelp(runner.execute.bind(runner)));
+```
+
+Bound methods may lose original parameter names at runtime and fall back to
+`arg0`, `arg1`, and so on.

package/docs/faq.md

@@ -0,0 +1,59 @@
+# FAQ
+
+## Which Node versions are supported?
+
+Node 20 or newer.
+
+## Should I use the library API or the CLI?
+
+Use `agentHelp(target)` when the target is already loaded in your program.
+
+Use the CLI when you want better TypeScript signatures from source files or
+declaration files:
+
+```sh
+npx agent-readable-ts ./src/widget.ts:Widget
+npx agent-readable-ts commander:Command
+```
+
+## Can runtime reflection recover TypeScript types?
+
+No. TypeScript types, interfaces, overloads, generic parameters, return types,
+and doc comments are erased from compiled JavaScript.
+
+The CLI can recover more type information by parsing `.ts` files or adjacent
+declaration files.
+
+## Why do some parameters show up as `arg0`?
+
+Parameter names come from `Function.prototype.toString()` when possible. Native
+functions, bound functions, destructured parameters, and some compiled output do
+not preserve useful names, so the library falls back to `arg0`, `arg1`, and so
+on.
+
+## Are constructors or getters invoked?
+
+No. Constructors are not called during introspection, and getters are not
+invoked.
+
+## Are private members shown?
+
+JavaScript `#private` fields and methods are not reflectable and never appear.
+
+TypeScript `private` and `protected` are compile-time constructs. The library
+excludes names starting with `_`, but runtime JavaScript cannot perfectly detect
+TypeScript visibility.
+
+## Does the CLI fetch packages automatically?
+
+No. Missing packages are only fetched when you pass `--install`.
+
+Fetched packages go into an isolated cache and are installed with
+`--ignore-scripts`. See [Getting Started](getting-started.md#on-demand-package-fetching).
+
+## Is this the same as the Python package?
+
+It is the TypeScript and JavaScript sibling of
+[agent-readable](https://github.com/zydo/agent-readable). The shared idea is the
+same: inspect the current API surface and author-provided usage rules before
+coding against an unfamiliar target.

package/docs/getting-started.md

@@ -0,0 +1,94 @@
+# Getting Started
+
+`agent-readable-ts` can be used as a library from TypeScript or JavaScript, and
+as a CLI for inspecting local files or npm packages.
+
+## Install
+
+```sh
+npm install agent-readable-ts
+```
+
+Node 20 or newer is required.
+
+## Library Usage
+
+```ts
+import { agentHelp } from "agent-readable-ts";
+
+console.log(agentHelp(SomeClass));        // class constructor
+console.log(agentHelp(new SomeClass()));  // class instance
+console.log(agentHelp(someFunction));     // function or arrow function
+console.log(agentHelp({ a: 1 }));         // plain object
+```
+
+The programmatic API uses runtime JavaScript reflection. It can show public
+members, parameter names when available, and `agentNotes()`/`agentHelp()` output,
+but it cannot recover TypeScript-only types from compiled JavaScript.
+
+## CLI Usage
+
+The CLI can inspect installed npm packages, local JavaScript files, and local
+TypeScript files.
+
+```sh
+npx agent-readable-ts commander
+npx agent-readable-ts commander:Command
+npx agent-readable-ts ./src/widget.ts:Widget
+```
+
+`commander` is only an example target. Use any trusted installed package, local
+module, or local TypeScript file.
+
+Usage:
+
+```sh
+agent-readable-ts [--install] <package-name>[:<export-name>]
+agent-readable-ts <module-path>[:<export-name>]
+```
+
+- `package-name`: an installed npm package, such as `commander`, `pino`, or
+  `@scope/package`.
+- `module-path`: a `.js`, `.mjs`, `.cjs`, or `.ts` file path relative to the
+  current directory.
+- `export-name`: the named export to document. Use dots for nested access, such
+  as `Things.Helper`.
+- `--install`: allow the CLI to fetch a package on demand when it is not
+  installed locally.
+
+If no export name is given for a package, all exports are listed. If no export
+name is given for a file, the module namespace object is documented.
+
+`.ts` files require `tsx`. It is included as a dev dependency in this repo, and
+`npx` resolves it automatically when running from this package.
+
+## One-Off Execution
+
+Use one of these when you do not want to add a dependency to the current project:
+
+```sh
+npx agent-readable-ts commander
+npm exec -- agent-readable-ts commander:Command
+pnpm dlx agent-readable-ts ./src/widget.ts:Widget
+```
+
+## On-Demand Package Fetching
+
+Packages already installed in the current project load directly. For anything
+else, the CLI refuses to fetch unless `--install` is passed:
+
+```sh
+npx agent-readable-ts --install left-pad
+```
+
+Fetched packages go into `~/.cache/agent-readable-ts`, or the directory named by
+`AGENT_READABLE_CACHE`. They are never installed into the current project.
+
+The install uses `npm install --ignore-scripts`, so package lifecycle scripts are
+not run. Cached packages load offline without requiring `--install` again.
+
+## Security
+
+The CLI imports packages and local modules in order to inspect them. Importing a
+module executes its top-level code. Only inspect packages and files you trust to
+run on your machine.

package/docs/why.md

@@ -0,0 +1,43 @@
+# Why agent-readable-ts?
+
+Coding agents often guess a library API from stale memory: inventing methods,
+using old signatures, or missing lifecycle rules that are not visible from a
+method list alone.
+
+`agent-readable-ts` gives agents a small, live, API-shaped context before they
+write code:
+
+- the public callable surface that can be discovered safely;
+- TypeScript signatures when the CLI can parse source or declaration files;
+- author-supplied usage rules from `agentNotes()`;
+- full custom guidance from `agentHelp()` when a library needs it.
+
+This reduces failed edit-test-retry loops and keeps the agent focused on the API
+that exists in the current project.
+
+## Why Not Just README Docs?
+
+README files are written for people and often cover happy-path examples. Coding
+agents need a compact answer to narrower questions:
+
+- What members exist on this object right now?
+- Which methods are public?
+- What is the current call shape?
+- Are there ordering, cleanup, async, or safety rules?
+
+`agent-readable-ts` puts that information next to the implementation and exposes
+it through one consistent inspection path.
+
+## Runtime and Source Inspection
+
+TypeScript type annotations do not exist at runtime. The library API therefore
+uses conservative JavaScript reflection. The CLI fills more gaps by parsing
+`.ts` source or adjacent `.d.ts` declaration files for packages and JavaScript
+modules.
+
+When type detail matters, prefer the CLI:
+
+```sh
+npx agent-readable-ts ./src/widget.ts:Widget
+npx agent-readable-ts commander:Command
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-readable-ts",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Attach agent-oriented documentation to any class, object, or function",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -17,6 +17,7 @@
     "agent-readable-ts": "dist/src/cli.js"
   },
   "files": [
+    "docs",
     "dist/src"
   ],
   "scripts": {