# Cross-Platform Compatibility

Use this reference when running or installing the skill on macOS, Windows, Linux, or CI.

## Compatibility Summary

| Area | macOS | Linux | Windows |
| --- | --- | --- | --- |
| `SKILL.md` workflow | Supported | Supported | Supported |
| `project_inventory.py` | Supported with Python 3.9+ | Supported with Python 3.9+ | Supported with Python 3.9+ |
| Python dependencies | Standard library only | Standard library only | Standard library only |
| Path handling | `pathlib` | `pathlib` | `pathlib` |
| Shell dependency | None in script | None in script | None in script |
| Generated Markdown paths | POSIX-style relative paths | POSIX-style relative paths | POSIX-style relative paths |

The script intentionally emits repository-relative paths with `/` separators so generated Markdown is stable across platforms and friendlier for URLs, GitHub, and RAG metadata.

## Python Invocation

macOS and Linux usually have one of these:

```sh
python3 skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated
python skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated
```

Windows PowerShell usually uses:

```powershell
py -3 skills\project-knowledge-builder\scripts\project_inventory.py --root . --out docs\project-knowledge\generated
python skills\project-knowledge-builder\scripts\project_inventory.py --root . --out docs\project-knowledge\generated
```

CI should prefer an explicit Python:

```sh
python -m py_compile skills/project-knowledge-builder/scripts/project_inventory.py
python skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated --json
```

## Command Substitutions

| Task | macOS/Linux | Windows PowerShell |
| --- | --- | --- |
| List docs | `find docs/project-knowledge -type f \| sort` | `Get-ChildItem docs/project-knowledge -Recurse -File \| Sort-Object FullName` |
| Search placeholders | `rg -n "TODO|TBD" docs/project-knowledge` | `rg -n "TODO|TBD" docs/project-knowledge` |
| Show git status | `git status --short` | `git status --short` |
| Remove temp output | `rm -rf ./kb-inventory` | `Remove-Item .\kb-inventory -Recurse -Force` |

`rg` is preferred where available. If `rg` is not installed, use the platform search available in the environment.

## Avoid In Skill Examples

- Hard-coded `/tmp` paths when the command should work on Windows.
- POSIX-only command chains such as `cmd1 && cmd2` in user-facing instructions when a PowerShell equivalent is needed.
- Shell glob assumptions that behave differently between zsh, bash, PowerShell, and cmd.
- Python code that depends on executable shebang behavior; Windows users should call `py -3 script.py`.

## Known Limits

- Java endpoint extraction is regex-based and intentionally conservative. It does not fully resolve constants, composed annotations, or inherited controller mappings.
- SQL table extraction looks for `CREATE TABLE`; tables created dynamically or through migrations in another DSL need manual documentation.
- Frontend route extraction scans route-like literals and view files; runtime-generated route data from APIs still requires backend menu/permission data or database export.
- Very large repositories may need `--max-files` tuning or additional ignore directories.