added AGENTS.md & DOCS

Author: dg

.gitattributes

@@ -1,8 +1,10 @@
 .gitattributes  export-ignore
 .github/        export-ignore
 .gitignore      export-ignore
+AGENTS.md       export-ignore
 dresscode.neon  export-ignore
 phpstan*.neon   export-ignore
+docs/           export-ignore
 tests/          export-ignore
 
 *               text=auto

AGENTS.md

@@ -0,0 +1,65 @@
+# To My Agents!
+
+It is my fervent wish that this file guide every AI coding agent working with code in this repository.
+
+## Documentation
+
+Any distilled, agent-facing documentation for this package - how it works
+internally and the rationale behind key design decisions - lives in `docs/`.
+Consult it before non-trivial changes; it is the source of truth from which the
+public manual is distilled.
+
+Two small classes, mostly clear from signatures; the value is a few traps - the
+help-text-as-schema parser, the `parse()` sentinel, and the two terminal checks.
+Read `docs/internals.md` before editing them.
+
+## Project Overview
+
+**Nette Command Line** is a tiny, zero-dependency library with two utilities:
+`Parser` (argument/option parsing, including help-text-driven definitions) and
+`Console` (terminal color output with capability detection).
+
+- **PHP Version**: 8.2 - 8.6
+- **Package**: `nette/command-line`
+
+## Essential Commands
+
+```bash
+# Run all tests
+vendor/bin/tester tests -s        # or: composer tester
+vendor/bin/tester tests/Parser.fluent.phpt -s
+
+# Static analysis (PHPStan level 8)
+composer phpstan
+```
+
+## Conventions
+
+- Every file starts with `declare(strict_types=1);`; **tabs**; everything typed;
+  DressCode.
+- Constants are modern PascalCase (`Parser::Optional`) with deprecated UPPERCASE
+  aliases kept for BC.
+- Tests are Nette Tester `.phpt` under `tests/` (require `bootstrap.php`); use
+  `test()` / `Assert::same` / `Assert::exception`, no comment before `test()`.
+
+## Working in this repo
+
+- **Help text *is* the schema.** `addFromHelp()` parses formatted help with two
+  regexes: the option name is the **last** flag on a line, the alias the first; a
+  `<file>`/`[type]` spec sets required/optional, `...` marks repeatable, `<a|b|c>` an
+  enum. The `$defaults` array merges over the parsed result (it supplies `RealPath`,
+  `Normalizer`, etc.); `RealPath` desugars into a `Normalizer`.
+- **`parse()` uses an `OptionPresent = true` sentinel.** A bare `--flag` yields the
+  literal `true`; a value is taken from the next token only if it doesn't start with
+  `-`. So an optional-value option used bare parses as **`true`, not its fallback** -
+  the **fallback applies only when the option is absent entirely**. A missing required
+  *positional argument* throws; a missing required *option* becomes `null`.
+- **`parseOnly()` is deliberately dumb** - it parses only the named options, never
+  validates, never throws (so `--help`/`--version` work despite a missing required
+  argument). Don't add validation to it.
+- **`Console::detectColors()` and `detectTerminal()` are separate on purpose.** Gate
+  *color* on `detectColors` (honors `NO_COLOR`/`FORCE_COLOR`), but gate
+  *interactive-only* features (progress bars, prompts) on `detectTerminal` (pure TTY)
+  - a user may disable color yet still be on a real terminal.
+- User-facing how-to (fluent `addSwitch`/`addOption`/`addArgument`, the help-text
+  format, color codes) is manual material and lives in the public web docs, not here.

docs/internals.md

@@ -0,0 +1,70 @@
+# CommandLine internals
+
+Two small classes; most of it is clear from signatures. This is the thin
+"conventions & traps" layer — the few facts that are expensive to rediscover.
+
+## Help text is the schema (`addFromHelp`)
+
+The clever, non-obvious part: `addFromHelp()` **parses formatted help text into
+option definitions** with two regexes. The outer one extracts each option line and
+its `(default: …)`; the inner one parses the option syntax itself, and its result
+determines everything:
+
+- `--long` / `-s, --long` → the option name is the **last** matched flag (`--long`),
+  the alias the first (`-s`) when they differ;
+- a value spec `<file>` (required), `[type]` (optional) or a bare word (`--width N`,
+  required) → whether the option takes a value; a trailing `...` → **repeatable**;
+  `<a|b|c>` → an **enum** (split on `|`);
+- a `(default: …)` (or a `[…]` value spec) → the option is optional with that
+  fallback.
+
+The whole matched flag string must be fully consumed by the inner regex or it throws
+`Unable to parse '…'`. The `$defaults` array passed alongside **merges over** the
+parsed values (it supplies what help text can't express: `RealPath`, `Normalizer`,
+`Enum`, `Repeatable`). `RealPath` is desugared into a `Normalizer` that resolves the
+path (composing with any user normalizer). The `ValueType` (`None`/`Optional`/
+`Required`) is then derived: no value spec → `None`; optional or has a default →
+`Optional`; else `Required`.
+
+## `parse()` and the `OptionPresent` sentinel
+
+`parse()` walks the args with a **positional cursor** (`current()`/`next()` over the
+positional options) alongside named-option lookup. A token starting with `-` is an
+option, anything else is a positional argument — so **options and arguments may
+interleave freely** (an argument can precede an option).
+
+The trap is the sentinel `OptionPresent = true`. A `--flag` with no `=value` yields
+this literal `true` as its "value". Then:
+
+- if the option takes a value and the sentinel is still present, the **next token is
+  consumed as the value only if it does not start with `-`**; otherwise a `Required`
+  option throws and an `Optional` one keeps the `true`.
+- so an optional-value option used bare (`--format`) parses as **`true`**, not its
+  fallback. The **fallback is used only when the option is absent entirely** (the
+  final fill-in pass). `enum` validation skips the `true` sentinel — but a
+  `normalizer` does **not**: it receives the raw `true`. And fallbacks are assigned
+  as-is, never normalized.
+
+The fill-in pass at the end assigns fallbacks to unused non-`Required` options,
+throws for a missing required **positional** argument (a missing required *option*
+just becomes `null`), and casts a repeatable value to an array. A repeatable option
+accumulates into a list; a non-repeatable one keeps the **last** occurrence.
+
+## `parseOnly()` is a deliberately dumb early-exit path
+
+`parseOnly(['--help', '--version'])` exists so info options work even when a required
+argument is missing. It parses **only** the named options, **ignores everything
+else, never validates, never throws**, and returns `null` for anything unused (but
+respects aliases). Do not add validation to it — that would defeat the "`--help`
+before the missing-argument error" use case.
+
+## Console: two distinct terminal checks
+
+`detectColors()` and `detectTerminal()` are **separate on purpose**. `detectTerminal`
+is the pure CLI+TTY check (`stream_isatty(STDOUT)`); `detectColors` builds on it and
+adds `NO_COLOR` (disables) and `FORCE_COLOR` (overrides the TTY check). The rule:
+gate **color** on `detectColors`, but gate **interactive-only features** (progress
+bars, line-rewriting, prompts) on `detectTerminal` — a user may set `NO_COLOR` yet
+still be on a real terminal that should get a progress indicator. `color($color)`
+with the string omitted emits the escape code with **no reset**, for building a
+sequence manually (it is the null *string*, not a null color, that skips the reset).