docs(transformation): AI Transformation motion — Variant B, group in Guides - #18
Closed
rs07-within wants to merge 9 commits into
Closed
docs(transformation): AI Transformation motion — Variant B, group in Guides#18rs07-within wants to merge 9 commits into
rs07-within wants to merge 9 commits into
Conversation
Bring the docs/transformation pages from PR #11 (add-transformation-playbook) forward onto current main, and sweep Klarity -> Within in prose so they match the rebranded site. Nav wiring and the new pages (readouts, opportunity loops) follow in later commits. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
New docs/transformation/readouts.mdx: how to produce a defensible, evidence-backed readout (business case first, observed vs inferred, depth before compression, interactive diagrams, pre- vs post-sale), with a synthetic prompt/output and a learnings section. Drafted by GPT 5.6 via Codex from REQUIREMENTS-FOR-CODEX.md (W1); verified against the brief's acceptance checks. Nav wiring follows in the nav commit. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Document a bounded recurring scan, add a synthetic ranked opportunity output, and make the readout evidence pull reproducible. The transformation overview now links the new evidence and readout paths. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Document the solution as dimensions instead of named tiers. Add the full customer-facing skill walkthrough because the existing track did not show the approval gates, package shape, or a concrete configuration. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fold Derrick's Advisor and MCP positioning into the existing page. Separate Advisor, the read-only Within MCP, and client-owned actions, and correct ADK's role from a surface to a builder method. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace internal shorthand, promotional claims, and unsupported absolutes with explicit evidence and control guidance. Correct maintenance to match the read-only MCP contract: the client owns baselines and diffs, while Within supplies current process data. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add the hierarchy-node drill-down and name the boundary between the L3 process graph and L4 activity timelines so developers can choose the smallest evidence pull. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Remove two negative-parallelism phrases flagged in review without changing the verified MCP examples or page flow. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Create the in-Guides navigation variant with the same page order as the tab branch and remove the duplicated opportunity guide. Readouts precede selection because they convert evidence into the decision brief. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
rs07-within
force-pushed
the
applai-322-transformation-group
branch
from
September 10, 2026 12:22
2a5b3e5 to
e38bad1
Compare
rs07-within
marked this pull request as ready for review
September 10, 2026 12:22
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.
What this is
Expands the developer docs (developers.within.ai) with the AI Transformation motion — the Improve layer of Discover -> Structure -> Improve — per APPLAI-322. Built on the content from PR #11, brought forward onto the rebranded
main(Klarity -> Within) and extended.This is one of two nav variants opened for comparison. The page content is identical in both PRs; only
docs/docs.jsondiffers. Draft on purpose: the Mintlify preview builds for review, but do not merge until we pick a variant and fold in the APPLAI-368 consolidation.Pages
New:
transformation/readouts.mdx— building defensible, evidence-backed readouts, with a learnings section.transformation/opportunity-loops.mdx— opportunity-scanning routines with a bounded clear / remediate / escalate loop.Ported from PR #11 and revised:
transformation.mdx(overview),objective,company-brain,use-case-selection,what-you-can-build(now carries the solution-space dimensions),where-you-build(Advisor vs MCP build location + the L3/L4 developer pull),non-technical-track(skill-build walkthrough),technical-track(ADK eight-step sequence),maintain-agents.Enriched:
guides/find-opportunities.mdx— added a synthetic ranked sample output.Nav in this variant: group inside Guides
Adds the transformation pages as a Drive AI transformation group inside the existing Guides tab (the approach PR #11 used). Smaller, less prominent nav change. The sibling PR is the alternative (a new top-level tab).
Relationship to the proposed user-docs MCP page (APPLAI-368)
The Agent Platform team has a proposed user-facing page, "Using the Within MCP" (Derrick, PR #27 on docs.within.ai,
user-docs/improve/within-mcp.mdx). It and this draft are complementary, not competing: that page is the user-facing "should I use the MCP, and what is it" layer; this is the developer "how to build with it" layer. Overlaps and contradictions to resolve before either publishes:where-you-build.mdxrestates the Advisor / MCP / client boundary that Derrick's page also covers. Resolution: treat his page as the canonical comparison; trim this page to the build-location decision and link out. Edit pending the page's published URL./guides/agent-builder. Build depth stays here; his page keeps the pointer. No duplication needed.security.mdxdoes not mention it. Add that line, pending confirmation with Agent Platform.Full section-by-section comparison and the consolidation proposal are on APPLAI-368.
Review
The Mintlify preview builds automatically on this PR; compare it against the sibling variant's preview. Hold merge until we choose a nav and apply the APPLAI-368 consolidation edits.
Refs: APPLAI-322 (parent), APPLAI-368 (comparison).
🤖 Generated with Claude Code
Sibling variant (compare the other nav): #17