docs: concept-clarity sweep — factual fixes + opening rewrites + site shell#148
Merged
Conversation
oracle-contributor-agreement
Bot
added
the
OCA Verified
A targeted sweep over content that did not match `src/locus/`. - GSAR claim partition names: `cited / supported / unsupported / mismatched` → `grounded / ungrounded / contradicted / complementary` (matches `src/locus/reasoning/gsar.py:172-175`). Hit `capabilities.md` and `FEATURES.md`; the homepage card was already fixed. - Event prefix list: docs claimed "9 prefixes" but the codebase has 10 — `research.*` was missing from the catalogue list in `capabilities.md` and `FEATURES.md`. Bumped event-constant count from "40+" to "60+" (actual: 65 `EV_*` constants in `src/locus/observability/emit.py`). - Pattern-count: `docs/img/patterns/README.md` said "six in-process multi-agent + A2A" on line 3, line 11 of the same file (and the seven actual `.svg` exports) said seven. Fixed. - Model id: swept `oci:openai.gpt-5` → `oci:openai.gpt-5.5` across every concept / how-to / provider page so example code matches what `LUIGI_FRA_API` actually serves today. The legitimate `openai.gpt-5-pro` reference in `how-to/oci-models.md` (the Responses-only model called out as unsupported) was left alone. - `docs/how-to/deploy.md:20`: `OCIBucketBackend(bucket=…)` → `bucket_name=` to match the actual init signature in `src/locus/memory/backends/oci_bucket.py:47-90`. As written, the snippet raised `TypeError` on import. - `docs/how-to/persist-conversations.md` lead-in rewritten: the "first four native subclasses" sentence didn't match the bullet list immediately above it. Replaced both with a clear native-vs-storage-backed split, removed the now-redundant tail paragraph. - `docs/concepts/providers/openai.md:58` had `gpt-4o, gpt-4.1, gpt-5, gpt-5, gpt-image-1` (duplicate `gpt-5`). Fixed. - `docs/how-to/quickstart.md:97` used `ToolStartEvent(args=a)` — actual field name is `arguments` (`src/locus/core/events.py:46`). Real bug; the snippet would match nothing. No prose rewrites in this commit; those follow. Signed-off-by: Federico Kamelhar <federico.kamelhar@oracle.com>
Two pages had openings that buried the payoff under jargon, and
seven more had OK openings that asked too much of the reader before
landing on what the page is for. This pass rewrites the first
paragraph (and one section per page where flagged) without churning
working prose elsewhere.
Restructured:
- `concepts/router.md` — leads with a concrete scenario ("Diagnose
the checkout API slowdown" → one of eight orchestration shapes)
instead of jumping to `GoalFrame` and `Protocol`. Added a 2-sentence
narrative bridge before the Five-layer diagram and an intuition
line before the four-signal ranking algorithm.
- `concepts/gsar.md` — opens with the failure mode vanilla
`grounding=True` misses (incident-response synthesis over-reaches
on individually-grounded claims) and frames GSAR as the upgrade,
with the arXiv link. Introduces the `G ⊔ U ⊔ X ⊔ K` symbols
before the formula instead of inside it.
Tightened:
- `concepts/agent.md` — frames `Agent` as the shared unit that
orchestrators / handoff / the router instantiate, not just "the
primary entry point."
- `concepts/models.md` — grounds the `oci:` / `openai:` prefix
concept (it's parsed by `get_model()`); adds provider-tree
wayfinding.
- `concepts/multi-agent.md` — three orienting questions before the
decision tree.
- `concepts/reasoning.md` — leads each of the three add-ons with
what it catches (wrong premises / hallucinations /
contradictions); explains the why of the fixed reflect→causal→
ground order.
- `concepts/hooks.md` — replaces abstract "cross-cutting concern"
framing with the concrete example list; surfaces
`HookPriority` constants above the numerical ranges.
- `concepts/skills.md` — drops "filesystem-first" implementation
noise; leads with the progressive-disclosure value prop.
- `concepts/state.md` — purpose-before-property opener.
- `concepts/streaming.md` — lifts the `match`-statement example to
the first code block (was buried at step 2).
Bug-adjacent: `concepts/memory-manager.md` had two links to
`checkpointers.md#cross-thread-store` — an anchor that didn't
exist. Added a `## Cross-thread store` section to
`concepts/checkpointers.md` explaining the `BaseStore` interface
(which is what those links promise), so the cross-page reference
now resolves under `mkdocs build --strict`.
Pages graded STRONG in the audit (agent-loop, tools, idempotency,
errors, retry, multi-agent subpages, observability, mcp, rag,
structured-output, conversation-management, deepagent,
multi-modal-providers, playbooks) were left alone — rewriting
working prose risks regression. Tutorial / API pages also out of
scope.
Signed-off-by: Federico Kamelhar <federico.kamelhar@oracle.com>
…h page Five connected site-shell improvements. - Homepage hero: replaced the Cognitive-router card description with the actual `locus.router` framing (meta-orchestration layer over the primitives). Added the arXiv link inline on the Grounded-reasoning card so readers know what GSAR is. Bumped every `oci:openai.gpt-5` → `gpt-5.5` in the example code. Cut the three hero bullets so they don't paraphrase the subtitle: bullet 1 now leads with the typed-`GoalFrame` + deterministic- registry detail (which the subtitle does not say); bullet 2 lost the "Better answers, built in" filler; all three get consistent terminal periods. - Sticky brand banner site-wide: `docs/stylesheets/locus.css` had `overflow-x: hidden` on `<html>` (line 7). That silently breaks `position: sticky` on every descendant — including the `.md-header` that `navigation.tabs.sticky` was supposed to pin. Switched to `overflow-x: clip`: same horizontal-scroll protection, but doesn't establish a scroll container, so the sticky header (and the tabs strip beneath it) now actually sticks on scroll. Also generalised the previous home-page-only brand-topic pin to fire on every page, so the diamond mark + "locus" + "MULTI-AGENT REASONING ORCHESTRATOR SDK" tagline stays put as the user scrolls — Material's default scroll-time topic-swap (which replaces the tagline with the page title) is fully suppressed. - "Concepts" tab lands on the multi-agent overview: added `navigation.indexes` to the Material features list and pinned `concepts/multi-agent.md` as the unnamed first entry under `Concepts:` in the nav, so clicking the top-nav tab opens the multi-agent overview directly. Removed the duplicate `Overview: concepts/multi-agent.md` under the Multi-agent submenu — mkdocs errors on a file appearing twice in nav, and `navigation.indexes` makes the section header itself the link. - Workbench docs: tightened the top of `docs/workbench.md` to lead with the actual two-click flow (Launch → Run) and removed the misleading "click the Ports panel" step — Vite's `5173.onAutoForward: openBrowserOnce` already opens the tab. Unified the Codespaces URL to include `?devcontainer_path=.devcontainer%2Fdevcontainer.json` on both the homepage button (`docs/index.md`) and the workbench page, so GitHub never picks a wrong devcontainer. - `workbench/README.md:18` had a stale `:3001` for the BFF port. Actual port is `:3101` (per `workbench/bff/src/server.ts:12` and the rendered `docs/workbench.md` architecture diagram). Signed-off-by: Federico Kamelhar <federico.kamelhar@oracle.com>
fede-kamel
force-pushed
the
docs/concept-clarity-sweep
branch
from
30e4fb9 to
981c66f
Compare
This was referenced May 12, 2026
Closed
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three-commit sweep over the docs site after a focused audit pass. Each commit is independently reviewable.
docs: fix factual drift against the codebase— 32 files. GSAR partition names, event-prefix count, six→seven,gpt-5→gpt-5.5model sweep,bucket=→bucket_name=, persist-conversations backend list, brokencross-thread-storeanchor groundwork,ToolStartEvent(args=…)→arguments=. No prose rewrites; only verifiable corrections againstsrc/locus/.docs: rewrite weak / dense openings on concept pages— 11 files. Restructured the two pages the audit graded WEAK (router.md,gsar.md) so the payoff lands before the jargon. Tightened the opening of seven OK pages (agent.md,models.md,multi-agent.md,reasoning.md,hooks.md,skills.md,state.md,streaming.md). Added aCross-thread storesection tocheckpointers.mdso the twomemory-manager.mdreferences resolve.docs(site): homepage hero, sticky brand banner, nav landing, workbench page— 5 files. Cognitive-router card rewrite + arXiv link on GSAR card + hero-bullet tightening; fixedoverflow-x: hiddenon<html>that was silently disablingposition: stickysite-wide; site-wide pin of the brand topic so scrolling doesn't replace the tagline with the page title;Conceptstab now lands on the multi-agent overview vianavigation.indexes; workbench page now reads as a two-click flow with the explicitdevcontainer_path; corrected the stale BFF port inworkbench/README.md.Why
Several rounds of "go through the entire docs" + "ensure concepts are well explained" turned up: incorrect claim-partition names, an out-of-date model id across 37 files, a broken anchor, a snippet that raised
TypeErroron import, a sticky-tabs feature that didn't work because of a single CSS rule, and a few concept pages that buried the payoff. This bundles all of it.Test plan
mkdocs build --strictpasses (it did locally — only the two intentional "out of nav" infos forFEATURES.md/legal.md)./concepts/router/and/concepts/gsar/— first 100 words on each should land on the payoff without unintroduced terms.grep -rn 'cited.*supported' docs/returns zero hits.grep -rn '40+ canonical' docs/returns zero hits.grep -c 'oci:openai.gpt-5\"' docs/returns zero hits.devcontainer_pathquery param.