docs(transformation): AI Transformation motion — Variant A (new top-level tab) - #19
Open
rs07-within wants to merge 9 commits into
Open
docs(transformation): AI Transformation motion — Variant A (new top-level tab)#19rs07-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 top-level tab variant and remove the duplicated opportunity guide from How-to. Place readouts before use-case selection because they turn evidence into the decision brief, and place Where you build before the two implementation tracks. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
Linear
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. All examples are synthetic; tool-call examples are verified against the live production Within MCP input schema (api.within.ai/mcp).Two variants, opened as a pair
This is one of two PRs with identical page content; only
docs/docs.json(the nav) differs, so the team can compare the two navigation shapes on their Mintlify previews and pick one. Do not merge until a variant is chosen and the APPLAI-368 consolidation is applied.Pages
New:
transformation/readouts.mdx(defensible, evidence-backed readouts + learnings);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— a synthetic ranked sample output.This variant: new top-level tab
Adds a new top-level AI Transformation tab holding the transformation pages as a Playbook group. Highest visibility, largest nav change.
Overlap with the proposed user-docs MCP page (APPLAI-368)
The Agent Platform team has a proposed user-facing page "Using the Within MCP" (docs.within.ai, PR #27). It and this draft are complementary — that page is the user "what/why" layer, this is the developer "how to build" layer. To consolidate before publish:
where-you-build.mdxrestates the Advisor / MCP / client boundary his page also covers. Make his page the canonical comparison; trim this to the build-location decision and link out once the page has a published URL./guides/agent-builder; build depth stays here.security.mdxdoes not. Add it, pending confirmation with Agent Platform.Full section-by-section comparison and the consolidation proposal are on APPLAI-368.
🤖 Generated with Claude Code
Sibling variant (compare the other nav): #20