Closes#40793
---
Docs-only repair from a full audit of developer-facing markdown against
the repository as source of truth. A new contributor following
`AGENTS.md` from the repo root currently hits missing files and commands
that cannot run; package docs and a workflow comment also drift from
reality.
**What was wrong**
- `AGENTS.md` listed root-level `pyproject.toml`, `uv.lock`, and
`Makefile` as key config files — none exist at the repo root (config is
per package under `libs/*/`).
- Setup/test/lint examples (`uv sync --all-groups`, `make test` / `lint`
/ `format`) had no working directory, so they fail if copy-pasted from
the root.
- The monorepo structure tree omitted `openwiki/` and `AGENTS.md`.
- `libs/README.md` omitted the `model-profiles/` package from its
directory list.
- Root `README.md` linked Deep Agents with `http://` while every other
docs link uses `https://`.
- The PR-title paragraph claimed scopes are mandatory “with no
exceptions”, but `pr_lint.yml` sets `requireScope: false` (only empty
`type():` parens are rejected).
- Grammar (“require” → “requires”), an unfinished editable-installs
sentence, incomplete `pr_lint.yml` scope comment (missing `openrouter`,
`typesafe`), and a stale `make help` line pointing at a non-existent
top-level Makefile.
**What changed**
- Clarified per-package config layout and required `cd` into
`libs/<package>` before `uv` / `make` commands.
- Completed the structure diagram; added `model-profiles/` to
`libs/README.md`.
- Switched Deep Agents links to `https://`.
- Aligned the scope guidance with actual CI behavior (documented, did
not change `requireScope`).
- Tightened the `pr_lint.yml` comment and removed the dead Makefile help
line.
No runtime code, tests, or CI logic changed — comments and markdown
only.
AI assistance was used to prepare this change; I reviewed the diff
against the repository layout.
Deepak Thorat