Phase 2 of #393. Content work, not navigation work. Do it after Phase 1, because the new structure is what makes these pages look wrong.
What's wrong
Three pages are far outside the size distribution of their neighbours:
| Page |
Words |
Neighbour median |
tutorials/working_with_controls |
3,286 |
~900 |
getting_started/attestations |
2,376 |
~600 |
client_reference/kosli_get_snapshot |
23,372 |
~500 |
Why it matters
working_with_controls and attestations are doing several jobs each, which is why they were hard to place: an oversized page is usually two or three pages that never got separated. Under Phase 1 they land in Risks & Controls and Discover Kosli > Core concepts respectively, next to pages a third their length, so the mismatch becomes visible.
kosli_get_snapshot is a different problem. At ~46x its sibling median it is almost certainly a live-docs generation bug, not authoring. It is a generated page, so it cannot be fixed here.
Tasks
URL impact
List old path → new path in the PR. /getting_started/attestations and /tutorials/working_with_controls both have external references, so their original URLs must resolve after the split.
Out of scope
- Do not hand-edit
client_reference/kosli_get_snapshot.md. update-cli-docs.yml runs rm -f client_reference/kosli*.md then regenerates on every CLI release, so an edit there is silently reverted.
Verification
Phase 2 of #393. Content work, not navigation work. Do it after Phase 1, because the new structure is what makes these pages look wrong.
What's wrong
Three pages are far outside the size distribution of their neighbours:
tutorials/working_with_controlsgetting_started/attestationsclient_reference/kosli_get_snapshotWhy it matters
working_with_controlsandattestationsare doing several jobs each, which is why they were hard to place: an oversized page is usually two or three pages that never got separated. Under Phase 1 they land inRisks & ControlsandDiscover Kosli > Core conceptsrespectively, next to pages a third their length, so the mismatch becomes visible.kosli_get_snapshotis a different problem. At ~46x its sibling median it is almost certainly a live-docs generation bug, not authoring. It is a generated page, so it cannot be fixed here.Tasks
tutorials/working_with_controls(3,286 w) along its actual jobs. Add redirects for any new paths and keep the original path resolving.getting_started/attestations(2,376 w). It is referenced fromkosli-dev/serveras/getting_started/attestations/, so that exact URL must keep working.client_reference/kosli_get_snapshotseparately. Start withscripts/add_livedocs.pyandscripts/live_docs_*_data.py; the fix is in the generator or upstream inkosli-dev/cli, never in the page. File as its own issue if it turns out to be a generator bug.URL impact
List old path → new path in the PR.
/getting_started/attestationsand/tutorials/working_with_controlsboth have external references, so their original URLs must resolve after the split.Out of scope
client_reference/kosli_get_snapshot.md.update-cli-docs.ymlrunsrm -f client_reference/kosli*.mdthen regenerates on every CLI release, so an edit there is silently reverted.Verification
python3 -m pytest tests/— every new page has a navigation entrymint broken-links— no new broken links, and internal links updated (redirects are not followed by this check)/getting_started/attestationsand/tutorials/working_with_controlsstill resolvepython3 scripts/audit_navigation.py --check— clean