docs/ excluded from npm tarball — README 'Extending OpenCLI' link is dead for installed users; override mechanism undiscoverable
- Dominant language
- JavaScript
- Stars
- 29.3k
- Forks
- 2.9k
- Avg merge
- 15h 36m
- Merged PRs (30d)
- 70
Description
## Problem
`package.json`'s `files` field ships `dist/src/`, `clis/`, `cli-manifest.json`, `scripts/`, `README.md`, `LICENSE` — **`docs/` is excluded**. But `README.md` ("## Extending OpenCLI") links to `./docs/guide/extending-opencli.md`, a repo-relative path that resolves only on GitHub. For anyone who `npm i -g @jackwener/opencli` and reads the bundled README, that link is dead.
That guide is the **only** documentation of the "Local overrides for official adapters" flow (`opencli adapter eject` / `reset` / `status` + sparse single-file override). The CLI exposes `opencli adapter --help`, but the *when/why/how* — sparse override semantics, update survival, `verify` running the override, the `doctor` shadow warning — lives solely in the unshipped guide.
## Why it matters (agent use case)
Driving opencli from an AI agent off a fresh npm install: the agent sees `adapter eject` in `--help` at best, with no conceptual guide, and the companion skills (`opencli-adapter-author`, `opencli-usage`) don't mention the official-adapter override path either. Result: agents re-fork whole adapters or — worse — edit files inside `node_modules/@jackwener/opencli/clis/`, which the next `npm -g` upgrade silently overwrites. (Hit exactly this during a customization attempt on a bundled adapter.)
## Suggested fix (either)
1. Add `docs/` (or `docs/guide/`) to `package.json` `files` so the tarball ships it and the README link resolves locally; **or**
2. Make the README "Extending OpenCLI" section self-contained — inline a short `adapter eject`/`reset`/`status` quickref so it doesn't depend on an unshipped file.
Option 1 is lower-effort and keeps a single source of truth.
— Written by Claude Code (Opus 4.8) on behalf of @0reo
Contributor guide
Research direction
Inspect package.json's files field, README.md's "Extending OpenCLI" section, and docs/guide/extending-opencli.md. Start by checking how the npm package includes documentation and how the README link resolves after installation; done means installed users can reach the override guidance without a dead link or missing guide.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, nodejs
- Domain
- build-system, cli, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100