Update docs

Author: AJenbo

docs/CLI.md

@@ -2,7 +2,8 @@
 
 PHPantom is a language server, but it also ships CLI tools for batch
 analysis and automated fixing. These run the same engine that powers the
-editor, so results are consistent.
+editor, so results are consistent between what you see in your editor
+and what CI reports.
 
 ## Modes
 
@@ -21,8 +22,49 @@ this automatically.
 ## `analyze`
 
 Scans PHP files and reports PHPantom diagnostics in a PHPStan-style
-table format. Use it to find spots where the LSP cannot resolve a
-symbol, so you can achieve full completion coverage.
+table format. The goal is full symbol resolution: every class, member,
+and function call in your codebase should be resolvable. When that
+holds, completion and hover work everywhere, and PHPStan gets the type
+information it needs at every level.
+
+Use it to find and fix the spots where the editor can't resolve a
+symbol, so you can achieve and maintain full type coverage across
+the project.
+
+### What it checks
+
+It doesn't try to find every possible bug. Its main focus is symbol
+resolution: every class, member, and function call should point to
+something real. It also catches basic correctness issues like wrong
+argument counts and missing interface implementations. When a codebase
+passes cleanly, completions work everywhere for every developer on the
+team.
+
+That makes it useful in a few situations:
+
+- **Teams that just want completions to work in their editor.** If
+  your goal is "every `->` and `::` resolves to something" rather
+  than "catch every possible runtime error," PHPantom's analysis
+  covers exactly that.
+- **As a companion to PHPStan at a moderate level.** A team running
+  PHPStan at level 4 (catching dead code and type mismatches) can add
+  PHPantom's analysis to enforce that every class, member, and function
+  is resolvable across the full codebase. PHPStan catches logic errors,
+  PHPantom catches structural gaps. Together they cover a useful quality
+  surface without the effort of configuring PHPStan at max level.
+- **As a quick sanity check.** Point it at a Composer project and it
+  reports what it finds. No baselines, no ignore files, no level to
+  choose. The only configuration worth knowing about is
+  `unresolved-member-access`: enable it in `.phpantom.toml` to also
+  flag member access on variables whose type could not be resolved
+  (off by default because it is noisy on untyped codebases).
+
+> [!NOTE]
+> There are still occasional false positives, though they are getting
+> fewer with each release. If you hit one, please
+> [report it](https://github.com/AJenbo/phpantom_lsp/issues).
+
+### Usage
 
 ```sh
 phpantom_lsp analyze                             # scan entire project
@@ -87,6 +129,10 @@ Each has a rule identifier shown below the message.
 Applies code fixes across the project. Specify which rules to run, or
 omit `--rule` to run all preferred native fixers.
 
+This is useful for cleaning up an entire codebase in one pass. For
+example, a project with hundreds of unused `use` statements can be
+cleaned up in seconds rather than file by file.
+
 ```sh
 phpantom_lsp fix                                  # apply all preferred fixers
 phpantom_lsp fix --rule unused_import             # only remove unused imports
@@ -156,13 +202,6 @@ phpantom_lsp fix --dry-run --project-root /path/to/app
  [DRY RUN] 1 fix in 1 file (not applied)
 ```
 
-Use `--dry-run` in CI to enforce that imports stay clean:
-
-```sh
-phpantom_lsp fix --dry-run --rule unused_import --project-root .
-# Exit code 2 means fixable issues exist. Fail the build.
-```
-
 ### Idempotency
 
 Running `fix` twice produces the same result as running it once. If
@@ -186,35 +225,78 @@ on available settings.
 
 ---
 
-## Common patterns
+## CI Integration
+
+PHPantom works well as a lightweight CI gate. It's a single static
+binary with no runtime dependencies (no PHP, no Composer, no Node). Drop
+it into a pipeline and point it at your project root.
+
+### Why use it in CI?
+
+Editor diagnostics only help the developer who has the editor open.
+CI analysis protects the whole team: no PR can merge if it introduces
+an unresolvable symbol, regardless of which editor each developer uses.
+Over time this keeps the codebase fully navigable, so completions,
+hover, and go-to-definition work everywhere for everyone.
+
+It also complements PHPStan rather than replacing it. PHPStan is better
+at catching logical errors, type mismatches, and dead code. PHPantom is
+better at catching structural gaps: unknown classes, unresolvable
+members, missing implementations. Running both gives you broad coverage
+without needing PHPStan at max level to get full symbol resolution.
+
+### GitHub Actions example
 
-### CI pipeline: diagnostics gate
+```yaml
+name: Type Coverage
+on: [push, pull_request]
 
-Fail the build when PHPantom finds unresolvable symbols:
+jobs:
+  phpantom:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Use --no-dev to catch production code that depends on dev-only
+      # packages (e.g. calling PHPUnit classes from application code).
+      - name: Install Composer dependencies
+        run: composer install --no-interaction --prefer-dist --no-dev
+
+      - name: Install PHPantom
+        run: |
+          curl -sL https://github.com/AJenbo/phpantom_lsp/releases/download/0.6.0/phpantom_lsp-x86_64-unknown-linux-gnu.tar.gz | tar xz
+          chmod +x phpantom_lsp
+
+      - name: Check type coverage
+        run: ./phpantom_lsp analyze --severity warning --no-colour src/
+```
+
+The `analyze` step fails the build if any class, member, or function
+cannot be resolved (including unused imports). The output is clean and
+readable in the CI log.
+
+### Common patterns
+
+**Diagnostics gate.** Fail the build when PHPantom finds unresolvable
+symbols:
 
 ```sh
 phpantom_lsp analyze --severity warning --project-root . --no-colour
 ```
 
-### CI pipeline: enforce clean imports
-
-Fail the build when unused imports exist:
+**Enforce clean imports.** Fail the build when unused imports exist:
 
 ```sh
 phpantom_lsp fix --dry-run --rule unused_import --project-root . --no-colour
 ```
 
-### Pre-commit hook: auto-fix imports
-
-Clean up imports before every commit:
+**Pre-commit hook.** Clean up imports before every commit:
 
 ```sh
 phpantom_lsp fix --rule unused_import --project-root .
 ```
 
-### Combine analyze and fix
-
-Run fixes first, then check what remains:
+**Combine analyze and fix.** Run fixes first, then check what remains:
 
 ```sh
 phpantom_lsp fix --project-root .

docs/todo.md

@@ -35,6 +35,7 @@ within the same impact tier.
 | D11 | [Invalid class-like kind in context](todo/diagnostics.md#d11-invalid-class-like-kind-in-context)                             | Medium | Low    |
 | F4  | [Return type and closure parameter type inlay hints](todo/lsp-features.md#f4-return-type-and-closure-parameter-type-inlay-hints) | Medium | Medium |
 | A36 | [Import all missing classes](todo/actions.md#a36-import-all-missing-classes) (bulk import)                                    | Medium | Low    |
+| F6  | [Machine-readable CLI output formats](todo/lsp-features.md#f6-machine-readable-cli-output-formats) (`--format github\|json`) | Medium | Low    |
 |     | **Release 0.8.0**                                                                                                            |        |        |
 
 > **Note:** F1 (Workspace symbol search), F2 (Document symbols), A8
@@ -133,6 +134,7 @@ unlikely to move the needle for most users.
 | FX4  | [`phpstan.missingType.iterableValue` — add `@return` with iterable type](todo/fix-cli.md#fx4-phpstanmissingtypeiterablevalue--add-return-with-iterable-type)                | Medium      | Medium         |
 | FX5  | [`phpstan.property.unused` / `phpstan.method.unused` — remove unused member](todo/fix-cli.md#fx5-phpstanpropertyunused--phpstanmethodunused--remove-unused-member)          | Low         | Low            |
 | FX6  | [`phpstan.generics.callSiteVarianceRedundant` — remove redundant variance](todo/fix-cli.md#fx6-phpstangenericscallsitevarianceredundant--remove-redundant-variance)         | Low         | Low            |
+| FX7  | [`add_return_type` — generate `@return` docblocks from function bodies](todo/fix-cli.md#fx7-add_return_type--generate-return-docblocks-from-function-bodies)                | Medium-High | Medium         |
 |      | **[LSP Features](todo/lsp-features.md)**                                                                                                                                    |             |                |
 | F5   | [Call hierarchy](todo/lsp-features.md#f5-call-hierarchy) (incoming/outgoing calls)                                                                                          | Medium      | Medium         |
 | F2   | [Partial result streaming via `$/progress`](todo/lsp-features.md#f2-partial-result-streaming-via-progress)                                                                  | Medium      | Medium-High    |

docs/todo/fix-cli.md

@@ -37,6 +37,19 @@ with side effects in the RHS (method calls, function calls). When the
 RHS is pure (literal, property access, simple expression), remove the
 entire statement.
 
+### FX7. `add_return_type` — Generate `@return` docblocks from function bodies
+
+Wire up the existing "Generate PHPDoc" code action's return-type
+inference to the fix CLI. When a function or method has a native
+`array` return type (or no return type at all) and the body contains
+enough information to infer a specific element type, add a `@return`
+tag with the inferred type (e.g. `@return list<Butterfly>`).
+
+This lets teams that want to reach PHPStan level 6 (require return
+type declarations) run a single command and get specific, useful
+return types across the entire codebase for free, instead of adding
+them by hand file by file.
+
 ---
 
 ## Planned PHPStan Rules

docs/todo/lsp-features.md

@@ -239,3 +239,30 @@ index (X4), the lookup becomes a simple index query.
 
 Consider implementing after X4 (full background indexing) ships, or
 accept the same scan-based latency that Find References currently has.
+
+## F6. Machine-readable CLI output formats
+
+**Impact: Medium · Effort: Low**
+
+Add a `--format` flag to `analyze` and `fix` that controls the output
+format. The default remains the current human-readable table.
+
+### Formats
+
+- **`github`** — Emit
+  [workflow commands](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-a-warning-message)
+  (`::warning file=...::message`) so diagnostics appear as inline
+  annotations on pull request diffs. This is the highest-priority
+  format because GitHub Actions is the most common CI environment for
+  PHP projects.
+- **`json`** — One JSON object per diagnostic (or a top-level array).
+  Enables integration with custom dashboards, editor plugins, and
+  other tooling that wants to consume PHPantom output programmatically.
+
+### Implementation
+
+The output logic in `analyse.rs` and `fix.rs` currently writes
+directly to stderr/stdout with ANSI formatting. Extract the rendering
+behind a trait or enum so each format can be selected at the call
+site. The `--no-colour` flag becomes redundant for non-table formats
+but should continue to work for the default table output.