PB-077: User and agent docs match the code
State: Proposed. Not approved for implementation. Priority: P2. Owner when approved: Master product (unassigned).
1. PR title and ID#
Correct user, agent and plan docs that disagree with the code (PB-077)
2. Business problem#
People follow the docs. Where docs describe behavior the code doesn't have, users lose trust and contributors build on wrong assumptions.
3. Current verified behavior#
Mismatches found in this assessment (code at b7b04cc):
| Doc | Says | Code |
|---|---|---|
docs/user-guide.md line 349 (Report a problem) |
adds your tenant id | redact.py removes GUIDs including the tenant id |
docs/agent.md |
workload views read agent status records | only workloads/evaluate.py reads them |
docs/enterprise-roadmap.md |
the pipeline mailbox is not built; names a results/ folder |
mailbox.py is built and uses status/ |
docs/workloads/plan.md §2.1 |
incidents are a meta.incidents Delta table |
workloads/incidents.py keeps a JSON document |
docs/workloads/continuation.md |
PR #79 open | merged |
docs/troubleshooting.md line 45 |
Fabric's catalog is embedded on the same page as Endorsed items | no embedded catalog on that page |
docs/troubleshooting.md line 12 |
update checks hit GitHub's limit of 60 an hour | the updater reads releases/download/... files, not the REST API (updater.py, main.rs), so that limit shouldn't apply (inference) |
docs/notebooks.md |
%%sql notebooks publish as Spark | publish converts them (inference; confirm before editing) |
4. Desired behavior#
Each row corrected. Where the doc describes a plan, it says it is a plan.
5. In scope and out of scope#
In scope: the rows above, plus any mismatch the reviewer finds in the same pages. Out of scope: security and install docs (PB-010), Preview labels (PB-078), code changes.
6. Architecture and files#
The docs in the table. docs/product/reviews/TEMPLATE.md already asks reviewers to check doc claims.
7. Functional requirements#
Each correction cites the file that implements the behavior in the PR description.
8. Nonfunctional requirements#
Follow the existing docs voice; keep the product name "Fabric Desktop by KratosBI".
9. Dependencies#
None. Coordinate the workloads plan edits with the Workload management thread, which owns that plan.
10. Security and compatibility#
Docs only.
11. Acceptance criteria#
- Every row fixed or explained as intentionally unchanged.
zensical buildstrict passes.
12. Unit and integration tests#
None.
13. Manual verification#
Reviewer reads each changed paragraph against the cited code.
14. Documentation#
This PR is the documentation.
15. Rollback#
Revert the commit.
16. Definition of Done#
Merged, docs build green, inventory limitations that mention these mismatches removed.
Need a hand?
Find a fix in troubleshooting, or share a reproducible issue with the community.
Get support ↗Improve this guide on GitHub ↗