docs(transformation): AI Transformation motion — Variant A (new top-level tab)

docs/docs.json

@@ -77,7 +77,6 @@
             "pages": [
               "guides/process-performer",
               "guides/state-of-team",
-              "guides/find-opportunities",
               "guides/transformation-thesis",
               "guides/chain-with-connectors",
               "guides/deep-research",
@@ -93,6 +92,28 @@
           }
         ]
       },
+      {
+        "tab": "AI Transformation",
+        "groups": [
+          {
+            "group": "Playbook",
+            "pages": [
+              "transformation",
+              "transformation/objective",
+              "transformation/company-brain",
+              "guides/find-opportunities",
+              "transformation/opportunity-loops",
+              "transformation/readouts",
+              "transformation/use-case-selection",
+              "transformation/what-you-can-build",
+              "transformation/where-you-build",
+              "transformation/non-technical-track",
+              "transformation/technical-track",
+              "transformation/maintain-agents"
+            ]
+          }
+        ]
+      },
       {
         "tab": "Tool reference",
         "groups": [

docs/guides/find-opportunities.mdx

@@ -1,54 +1,67 @@
 ---
 title: "Find transformation opportunities"
-description: "Rank the highest-leverage automation and transformation candidates across the index."
+description: "Find and rank automation and transformation candidates across the process index."
 icon: "magnifying-glass-chart"
 ---
 
-A platform lead, AI architect, or transformation owner asks where to focus next. This is the "spin up multiple agents to scan the entire process tree" use case — agents should fan out in parallel across the hierarchy.
+Use this pattern when a platform lead, AI architect, or transformation owner needs a broad scan of the process tree. Independent process reads can run in parallel, but the scan still needs a bounded scope, evidence threshold, and stopping condition.
 
 ## Example prompts
 
-- "Find the highest-leverage automation opportunities in our P2P value stream."
+- "Find the automation opportunities with the strongest evidence and expected impact in our procure-to-pay value stream."
 - "Where in our close cycle should we focus next?"
 - "Scan our org for duplicate invoice processing across geographies."
 
 ## End-to-end recipe
 
 <Steps>
   <Step title="Confirm the workspace">
-    Call [`list_accessible_workspaces`](/tools/workspace) and switch if needed.
+    Call [`list_accessible_workspaces`](/tools/workspace). If the wrong workspace is active, reconnect with OAuth or use an API key created in the intended workspace before continuing.
   </Step>
   <Step title="Build the work queue">
     Call [`get_process_hierarchy`](/tools/process-index) — the whole tree, or filtered to the value stream of interest. The leaves become your work queue.
   </Step>
   <Step title="Fan out in parallel across leaves">
     For each leaf:
-    - [`get_process_details`](/tools/process-index) — current version, steps, dependencies. Note step count, manual vs system steps, exception count.
-    - [`get_process_observations`](/tools/observations-and-changes) — exception volume per process (default summary verbosity).
+    - [`get_process_details`](/tools/process-index) — current version, steps, dependencies, and relevant attributes.
+    - [`get_process_observations`](/tools/observations-and-changes) — a bounded set of captured runs in summary mode. Record the returned count without treating it as total process volume.
 
     <Tip>
-      The MCP is stateless per call. There's no penalty for parallel reads — fan out aggressively.
+      The MCP is stateless per call, so independent reads can run in parallel. Cap each batch so the scan stays within the routine's time and output budget.
     </Tip>
   </Step>
-  <Step title="Hunt high-leverage patterns in the index">
-    Call [`search`](/tools/entry-points) directly on the index with pattern queries: "manual approval", "duplicate entry", "data re-keying", "exception handling", "swivel-chair workflow". For each hit, [`fetch`](/tools/entry-points) the process to confirm the pattern is real, not just a name match.
+  <Step title="Find material patterns in the index">
+    Call [`search`](/tools/entry-points) directly on the index with pattern queries: "manual approval", "duplicate entry", "data re-keying", "exception handling", "swivel-chair workflow". For each hit, [`fetch`](/tools/entry-points) the process to confirm the pattern appears in the process itself rather than only in its name.
   </Step>
   <Step title="Check process attributes">
     Inspect the `attributes` field already returned by [`get_process_details`](/tools/process-index) — "automation status", "system of record", "control level", or similar attributes that help rank candidates.
   </Step>
   <Step title="Confirm each top candidate">
     For each top candidate:
-    - [`get_process_observations`](/tools/observations-and-changes) with `verbosity="full"` — confirm the deviation or manual pattern with concrete evidence.
+    - [`get_process_observations`](/tools/observations-and-changes) with `verbosity="summary"` — identify representative runs and competing evidence.
+    - [`get_observation_citation`](/tools/observations-and-changes) at low or medium verbosity — inspect one activity block at a time for the material behavioral claims the brief will make.
     - Read the `dependencies` field already returned by [`get_process_details`](/tools/process-index) for a first cut at blast radius.
   </Step>
   <Step title="Synthesize a ranked candidate set">
-    Process IDs, observation counts, dependency depth, similarity to known patterns, evidence trail.
+    Include process identifiers, the bounded observation count, dependency depth, pattern signal, counterevidence, uncertainty, and the next validation step.
   </Step>
 </Steps>
 
+## Sample output
+
+The candidate set below is synthetic. Its identifiers and counts show the shape of a useful result, not customer data.
+
+| Rank | Process | Observations reviewed | Dependency depth | Pattern signal | Evidence pointer |
+|---|---|---:|---:|---|---|
+| 1 | Resolve shipment exceptions | 12 | 3 | Staff gathered the same context manually in 9 of 12 captured runs | `process-example-001`; `observation-example-101` to `observation-example-109` |
+| 2 | Reconcile supplier statements | 8 | 2 | Six runs repeated an export, comparison, and re-entry sequence | `process-example-002`; `observation-example-201` to `observation-example-206` |
+| 3 | Review temporary access requests | 15 | 1 | Ten runs paused while reviewers looked for the same missing approval evidence | `process-example-003`; `observation-example-301` to `observation-example-310` |
+
+The first candidate ranks highest because the repeated pattern has the broadest downstream reach. The evidence does not yet prove that an agent is the right answer. The next step is to inspect representative activity timelines, confirm the required system access, and compare a skill, a deterministic flow, and a process change.
+
 ## What to surface in the brief
 
 - A ranked list of candidate processes
-- For each: observation count, dependency depth, pattern signal
-- Citable process IDs and observation timestamps
+- For each: bounded observation count, dependency depth, pattern signal, and counterevidence
+- Citable process resource keys and observation resource keys or timestamps
 - Gaps where the workspace doesn't have enough evidence yet

docs/transformation.mdx

@@ -0,0 +1,47 @@
+---
+title: "Drive AI transformation"
+description: "The motion that turns how your organization runs into skills, agents, and automations."
+icon: "compass"
+---
+
+The motion has three phases. [Discover](/transformation/company-brain) captures how work happens, [Structure](/transformation/company-brain#structure) makes sense of it, and Improve builds skills and agents on top. Within runs this as a continuous loop rather than a one-time project. See [Discover → Structure → Improve](/concepts/discover-structure-improve) for the model itself; these pages are how you run it.
+
+Start by naming a business objective and the technology constraints the solution must satisfy. These constraints keep the recommendation tied to systems your organization can approve and operate.
+
+## The Company Brain
+
+These pages use Company Brain for the living map of how your organization operates. It combines the [Process Index](/concepts/process-index), which holds processes with their steps, dependencies, and versions, with [Artifacts](/concepts/artifacts), the source documents and recordings behind them.
+
+Use this evidence to test assumptions about the process instead of relying on a generic template.
+
+## Where to start
+
+<Columns cols={2}>
+  <Card title="Set the objective" icon="bullseye" href="/transformation/objective">
+    Name the outcome in business terms before choosing any technology.
+  </Card>
+  <Card title="Build the Company Brain" icon="brain" href="/transformation/company-brain">
+    Turn on Companion, then spend time in what it captures.
+  </Card>
+  <Card title="Find opportunities" icon="magnifying-glass-chart" href="/guides/find-opportunities">
+    Scan the process tree and rank candidates against the evidence.
+  </Card>
+  <Card title="Keep the scan running" icon="arrows-rotate" href="/transformation/opportunity-loops">
+    Re-scan as capture grows and report newly supported signals.
+  </Card>
+  <Card title="Build a defensible readout" icon="presentation-screen" href="/transformation/readouts">
+    Connect the objective, impact, evidence, uncertainty, and next decision.
+  </Card>
+  <Card title="Pick the right use case" icon="list-check" href="/transformation/use-case-selection">
+    Screen candidates against evidence, feasibility, controls, and materiality.
+  </Card>
+  <Card title="What you can build" icon="cubes" href="/transformation/what-you-can-build">
+    Skills, Integration Flows, Managed Agents, and context bundles.
+  </Card>
+  <Card title="Where you build" icon="table-columns" href="/transformation/where-you-build">
+    Choose between Advisor and an AI client connected through the MCP.
+  </Card>
+  <Card title="Keep agents current" icon="arrows-rotate" href="/transformation/maintain-agents">
+    A build is a product. Refresh it as the business moves.
+  </Card>
+</Columns>

docs/transformation/company-brain.mdx

@@ -0,0 +1,76 @@
+---
+title: "Build the Company Brain"
+description: "Turn on Companion to capture how work actually happens, then spend time in what it captures before building anything."
+icon: "brain"
+---
+
+The Company Brain provides the process context used throughout the transformation workflow. This page covers the first two phases: capturing how work happens and reviewing what was captured.
+
+## Discover
+
+[Companion](/concepts/discover-structure-improve) captures work as participating team members perform it. It processes the captured activity to remove detected PII and user attribution, then organizes the result into a queryable map of processes and value streams.
+
+Capture can run across several people at once, which helps reveal process variation that interviews and written procedures may miss. The Interviewer can add context for work Companion cannot observe.
+
+Discover still needs a defined scope, clear communication, and enough coverage to support the decisions you plan to make.
+
+<Steps>
+  <Step title="Enable Companion for the team">
+    Follow the deployment guidance for your environment, then have participating team members use it while they perform the work in scope.
+  </Step>
+
+  <Step title="Select the right scope of users">
+    Choose the people who actually perform the work in the processes you care about. They are who you learn from.
+  </Step>
+
+  <Step title="Make sure that scope is sufficient">
+    Include enough people and natural variation to support the intended analysis. A single person's sessions may not represent the process across roles, regions, or exception types.
+  </Step>
+
+  <Step title="Run a kickoff">
+    Explain the scope, collection period, support path, and expected participation before capture begins.
+  </Step>
+
+  <Step title="Explain the value to users">
+    Be transparent about what Companion captures, how the data is processed, who can access the result, and how the analysis will be used. Address questions about privacy and role impact directly rather than leaving participants to infer the answers.
+  </Step>
+
+  <Step title="Help them feel part of it">
+    Give the people doing the work a way to correct missing context and review conclusions that affect their process.
+  </Step>
+
+  <Step title="Encourage Signals">
+    Ask people to contribute Signals during sessions, including effective practices and recurring friction that may not be clear from the activity sequence alone.
+  </Step>
+
+  <Step title="Keep it on, and make it recurring">
+    Run Companion for at least two weeks per cycle, and repeat at least four times a year. Work changes, and a recurring cadence keeps the Company Brain a live picture rather than a one-time snapshot.
+  </Step>
+</Steps>
+
+## Structure
+
+Once Companion has run, review the resulting Company Brain before selecting a build. This is where you check whether the available evidence supports the scope and assumptions behind the objective.
+
+### Explore the visualizations
+
+Start at the value-stream level and drill down to the processes relevant to the objective.
+
+### Review the process steps
+
+Inspect the captured activities to see where time goes, handoffs fail, or people move repeatedly between tools.
+
+### Ask Advisor
+
+When a pattern needs explanation, ask Advisor to analyze it, generate a visualization, or prepare a time-and-motion view.
+
+```text
+How does our vendor-onboarding process actually work today, and where do we
+lose the most time?
+```
+
+The point of Structure is to build intuition for your own operation before you build anything on top of it.
+
+<Note>
+  You can ask the same questions from any MCP client. [Help a process performer](/guides/process-performer) and [State-of-the-team report](/guides/state-of-team) show the tool chains behind this kind of exploration.
+</Note>

docs/transformation/maintain-agents.mdx

@@ -0,0 +1,67 @@
+---
+title: "Keep agents current"
+description: "Compare an existing build with current process evidence and retest what changed."
+icon: "arrows-rotate"
+---
+
+A released agent depends on process assumptions, source material, tool contracts, and controls that can change. Maintenance starts by recording those dependencies when the agent ships, then checking them on a defined schedule or after a known process change.
+
+## Record the baseline
+
+Keep the following with the agent's code and evaluations:
+
+- the process resource key and version used for the build
+- the observation set or evidence summary used to justify behavior
+- the policies, dependencies, tools, and model configuration the agent relies on
+- the evaluation set and release result
+- the owner and next review date
+
+This gives the next review a known comparison point. The Within MCP supplies the current process evidence; your repository or AI client stores the prior baseline and performs the comparison.
+
+## Review current evidence
+
+Start with the recent workspace change feed, then retrieve the current details for processes used by the agent.
+
+```javascript
+get_recent_process_changes({ "limit": 50 })
+
+get_process_details({
+  "process_resource_key": "<PROCESS_RESOURCE_KEY>",
+  "scope": ["tasks", "dependencies", "policies", "history"]
+})
+```
+
+`get_recent_process_changes` returns a bounded feed of recent changes. It does not accept a date cutoff, so do not treat it as proof that nothing changed before the returned window. Use the saved resource keys and versions to check each process the agent depends on.
+
+Where behavior matters, review current observations as well. Captured activity can show that the documented process stayed the same while execution, exceptions, or systems changed.
+
+## Classify the change
+
+Not every difference requires the same response.
+
+| Change | Example | Response |
+|---|---|---|
+| Presentation | A field or step was renamed without changing its meaning | Update references and rerun affected evaluations |
+| Behavioral | A rule, exception, input, or handoff changed | Revise the build and rerun the full evaluation set |
+| Structural | The objective, owner, system boundary, or required approval changed | Return to use-case selection and design before rebuilding |
+
+The classification is a review decision, not an MCP verdict. Confirm material changes with the process owner before changing production behavior.
+
+## Ask for a maintenance review
+
+```text
+Compare this agent's saved process baseline with the current Company Brain.
+List the changes, classify each as presentation, behavioral, or structural,
+and identify the evaluations that must run again. Do not modify the agent until
+I approve the proposed response.
+```
+
+## Use a recurring cadence
+
+Run [Companion](/transformation/company-brain) often enough to cover the process and exceptions the agent depends on. A maintenance review is only as current as the underlying capture and published process version.
+
+After an approved update, save the new baseline, run the required evaluations, and record the release result. Keep the previous version available for rollback according to your deployment controls.
+
+<Note>
+  [Process observations](/tools/observations-and-changes) documents the change feed, observation summaries, and activity timelines used in this review.
+</Note>