@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/audio-setup-mixers/references/api.md

@@ -0,0 +1,162 @@
+## What this skill does and does not automate
+
+Every `AudioMixer` in the Editor is really an `AudioMixerController`, and every `AudioMixerGroup` is
+an `AudioMixerGroupController`. Those two controller types are **not public**, and the authoring
+calls — creating a mixer, creating a group, re-parenting a group, changing a group's volume — exist
+only on them.
+
+This skill deliberately does not use them. Unity makes no stability commitment for non-public API,
+so a skill built on one can break silently between versions: the call fails at runtime rather than
+at compile time, and the user cannot tell that from a Unity bug.
+
+What matters is that the split is favorable. Each of those controllers derives from a public runtime
+type — `UnityEngine.Audio.AudioMixer` and `UnityEngine.Audio.AudioMixerGroup` respectively — and
+that public base is what every read and write below goes through. So **everything this skill needs
+in order to inspect a mixer and route audio into it is public API**:
+
+| Operation | Route |
+|---|---|
+| Find the project's mixers | public — `AssetDatabase` + `UnityEngine.Audio.AudioMixer` |
+| List a mixer's groups | public — `AudioMixer.FindMatchingGroups` |
+| Read an Audio Source's current group | public — `AudioSource.outputAudioMixerGroup` |
+| Assign a group to an Audio Source | public — `AudioSource.outputAudioMixerGroup` |
+| **Create a mixer or a group, change a group volume** | **not available** — the user does this in the Audio Mixer window |
+
+So the division of labor is: the skill inventories what exists, proposes the routing, asks the user
+to add any missing groups (two clicks in a window they already have open), and then does all the
+routing itself. The tedious part — walking dozens of Audio Sources and classifying them — is the
+part that was worth automating anyway.
+
+All snippets below are written for `unity command script eval --caller plugin --skill audio-setup-mixers --code '<snippet>'`: fully qualified, no
+`using` directives, returning their result rather than logging it.
+
+## Inventory the project's mixers and their groups
+
+```csharp
+// Scope the search to Assets. Unscoped, FindAssets also walks read-only packages, so the
+// inventory fills up with mixers the user did not author and cannot edit. Measured on one
+// project: t:Material returned 81 unscoped against 9 under Assets, t:Shader 204 against 22.
+// The only overloads are (string) and (string, string[] searchInFolders) — there is no
+// SearchMode parameter.
+var guids = UnityEditor.AssetDatabase.FindAssets("t:AudioMixer", new[] { "Assets" });
+if (guids.Length == 0) { return "no AudioMixer assets under Assets/"; }
+
+var rows = new System.Collections.Generic.List<string>();
+foreach (var guid in guids)
+{
+    var path = UnityEditor.AssetDatabase.GUIDToAssetPath(guid);
+    var mixer = UnityEditor.AssetDatabase.LoadAssetAtPath<UnityEngine.Audio.AudioMixer>(path);
+    var groups = mixer.FindMatchingGroups("");
+    var names = System.Linq.Enumerable.Select(groups, g => g.name);
+    rows.Add($"{path}  ({groups.Length} groups): {string.Join(", ", names)}");
+}
+return string.Join("\n", rows);
+```
+
+`FindMatchingGroups("")` returns every group in the mixer as the public `AudioMixerGroup` type,
+which is what routing needs. It returns a flat list — it does not describe the parent/child shape.
+If the hierarchy matters, read it off the Audio Mixer window with the user rather than reaching for
+the non-public tree API.
+
+## Read what the scene's Audio Sources are currently routed to
+
+```csharp
+var sources = UnityEngine.Object.FindObjectsByType<UnityEngine.AudioSource>(
+    UnityEngine.FindObjectsInactive.Include, UnityEngine.FindObjectsSortMode.None);
+
+var rows = new System.Collections.Generic.List<string>();
+foreach (var source in sources)
+{
+    var group = source.outputAudioMixerGroup;
+    rows.Add($"{source.gameObject.name}: clip={(source.clip != null ? source.clip.name : "<none>")}, "
+           + $"group={(group != null ? group.name : "<none — routes to Master>")}");
+}
+return rows.Count == 0 ? "no Audio Sources in the open scene" : string.Join("\n", rows);
+```
+
+Inactive objects are included on purpose: a disabled Audio Source still ships with the scene and
+still needs routing.
+
+## Assign groups to Audio Sources
+
+This is the one write this skill performs. `AudioSource.outputAudioMixerGroup` is typed as the
+public `AudioMixerGroup`, and the objects returned by `FindMatchingGroups` are assignable to it, so
+there is no cast and no reflection.
+
+**Key the mapping on whichever identifier you actually classified by.** Step 2 classifies from the
+**clip asset name** first and falls back to the GameObject name, so the mapping has to accept either
+— keying it on GameObject name alone silently drops every source you classified by its clip.
+
+```csharp
+var mixer = UnityEditor.AssetDatabase.LoadAssetAtPath<UnityEngine.Audio.AudioMixer>(
+    "Assets/Audio/TheMixer.mixer");
+
+// Keys may be a clip asset name or a GameObject name — whichever you classified from.
+var assignments = new System.Collections.Generic.Dictionary<string, string> {
+    { "FootStep4_Sound", "Foley" },   // clip name
+    { "MenuMusic",       "Music" },   // GameObject name
+};
+
+var sources = UnityEngine.Object.FindObjectsByType<UnityEngine.AudioSource>(
+    UnityEngine.FindObjectsInactive.Include, UnityEngine.FindObjectsSortMode.None);
+
+var done = new System.Collections.Generic.List<string>();
+var noSuchGroup = new System.Collections.Generic.List<string>();
+var unassigned = new System.Collections.Generic.List<string>();
+
+UnityEditor.Undo.IncrementCurrentGroup();
+UnityEditor.Undo.SetCurrentGroupName("Route Audio Sources to mixer groups");
+
+foreach (var source in sources)
+{
+    var clipName = source.clip != null ? source.clip.name : null;
+    string wanted = null;
+    if (clipName != null) { assignments.TryGetValue(clipName, out wanted); }
+    if (wanted == null) { assignments.TryGetValue(source.gameObject.name, out wanted); }
+
+    if (wanted == null)
+    {
+        // Never skip silently — an unmatched source is a result the user has to see.
+        unassigned.Add($"{source.gameObject.name} (clip={clipName ?? "<none>"})");
+        continue;
+    }
+
+    var group = System.Array.Find(mixer.FindMatchingGroups(""), g => g.name == wanted);
+    if (group == null) { noSuchGroup.Add($"{source.gameObject.name} -> {wanted}"); continue; }
+
+    UnityEditor.Undo.RegisterCompleteObjectUndo(source, "Route Audio Source");
+    source.outputAudioMixerGroup = group;
+    UnityEditor.EditorUtility.SetDirty(source);
+    done.Add($"{source.gameObject.name} -> {group.name}");
+}
+
+UnityEditor.Undo.FlushUndoRecordObjects();
+UnityEditor.Undo.CollapseUndoOperations(UnityEditor.Undo.GetCurrentGroup());
+
+var report = $"routed {done.Count}: {string.Join(", ", done)}";
+if (noSuchGroup.Count > 0) { report += $"\nNO SUCH GROUP (create it first): {string.Join(", ", noSuchGroup)}"; }
+if (unassigned.Count > 0) { report += $"\nNOT IN THE MAPPING (unrouted): {string.Join(", ", unassigned)}"; }
+return report;
+```
+
+Three things to carry through to the user:
+
+- **The scene changed, not the mixer asset.** `outputAudioMixerGroup` lives on the Audio Source, so
+  the routing only persists once the scene is saved
+  (`UnityEditor.SceneManagement.EditorSceneManager.SaveOpenScenes()`). Say so rather than assuming.
+- **Report the `NO SUCH GROUP` list explicitly.** A group the user hasn't created yet is the normal
+  case in this flow, not an error to swallow. Show it and ask them to add those groups.
+- **Report `NOT IN THE MAPPING` too.** Those are sources your classification missed. Reporting
+  "routed 4" while three sources were quietly skipped is the worst outcome available here, because it
+  reads as success.
+
+## Asking the user to add a group
+
+There is no supported programmatic route, so hand over precisely rather than vaguely:
+
+> In the Audio Mixer window (Window → Audio → Audio Mixer), select **TheMixer**, then click the
+> **+** next to Groups and name the new group **SFX**. Drag it under Master if it isn't already.
+> Tell me when it's there and I'll route the sources.
+
+Then re-run the inventory snippet to confirm the group exists before routing — don't assume the
+user did it, and don't assume they spelled it the way you asked.

package/skills/build-gtk/SECURITY.md

@@ -0,0 +1,16 @@
+# Security notes: build-gtk
+
+This skill has the agent read state from the user's open Unity Editor through `unity command script eval` when it checks a suspected fault in Play mode. Automated skill scanners flag that as a powerful capability. It is intentional, and it is limited by the safeguards below.
+
+## Accepted risks
+
+| Risk | Capability | Why it is accepted |
+|---|---|---|
+| `SEC_POWER_CAP` | Runs C# in the user's open Editor through `unity command script eval` | It only reaches the Editor the user already has open, on their own machine, as that user, so it grants nothing they couldn't do themselves. `script eval` sits behind the Pipeline capability gate. No code fetched from a remote source is run. The skill uses it only to read state while chasing a suspected fault, and uses `unity command console status` for the console check. |
+
+## Mitigations
+
+- **Only the user's own Editor.** `unity command script eval` talks to the Editor open on this machine. It can't reach another machine or another user's Editor.
+- **Capability gate.** `script eval` is only available when the project's Pipeline package provides it.
+- **No remote code.** The agent runs C# it writes itself to read Editor state. Nothing downloaded from outside is executed.
+- **Read only, once.** The skill enters Play mode at most once, to chase a fault it already suspects, and reads state instead of adding logging to the user's scripts.

package/skills/build-gtk/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: build-gtk
+description: >-
+  Builds graph tools with Unity Graph Toolkit (GTK) on 6.6+, state machines on 6.7+, and importers for
+  runtime assets. Use this skill for graph, node or state machine editors, or GraphView migrations. Not
+  for Shader Graph, VFX Graph or Animator.
+required_editor_version: ">=6000.6"
+---
+
+# Unity Graph Toolkit (GTK)
+
+Build Editor graph tools and state machine tools on Unity's Graph Toolkit module, using only its
+public API in the `Unity.GraphToolkit.Editor` namespace.
+
+## Important
+
+- Use the unity cli (`unity command --format json`) and the `unity-cli` and `unity-pipeline` skills for
+  each step.
+- Create a restore point you can roll back to if your changes fail.
+- Do only what's asked. Don't change unrelated assets or files.
+- Never leave verification code in the user's script. Never build logging or detection they didn't ask
+  for. See [Final step](#final-step).
+- Avoid long explanations.
+- **Graph Toolkit is a built-in module, not a package.** Never add `com.unity.graphtoolkit` to the
+  manifest; it is a deprecated shim. Editor code needs no asmdef reference to use it.
+- **Use only the public API.** If a draft uses any name from the left column, stop and rewrite it with
+  the right column:
+
+  | Never write | Write instead |
+  |---|---|
+  | `GraphModel`, `GraphObject`, `GraphTool`, `Stencil`, `BaseGraphTool` | `Graph` and `GraphDatabase` |
+  | `NodeModel`, `PortModel`, `WireModel` | `Node`, `IPort`, `Wire` |
+  | `StateModel`, `TransitionModel`, `ConditionModel` | `State`, `ITransition`, `Condition<T>` |
+  | `GraphViewEditorWindow`, `GraphElementsExtensionMethodsCache`, `ModelView` | the window is provided; `NodeView<T>` on 6000.7+ for custom UI |
+  | `UnityEditor.Experimental.GraphView`, `graphViewChanged`, `Port.Create` | model the tool as `Graph` and `Node` classes; track changes in `OnGraphChanged` |
+  | `com.unity.graphtoolkit` in the manifest | nothing; the module is built in |
+
+- **Spell members exactly.** Properties are PascalCase (`FirstConnectedPort`, `IsConnected`),
+  attributes take positional arguments, and IDs are `Hash128`, not strings. Look up any member you
+  have not seen in the docs or references instead of guessing it.
+- **Every authoring class is `[Serializable]`** (graph, node, state, condition, self transition) and
+  lives in Editor-only code. Otherwise nodes reset or vanish after a domain reload.
+- **Keep runtime assemblies free of `Unity.GraphToolkit.Editor`.** Guard visualization calls with
+  `#if UNITY_EDITOR`, because the module is Editor-only and any reference to it breaks the player build.
+- **Use `LoadGraphForImporter` (not `LoadGraph`) inside a `ScriptedImporter`.** The state machine
+  equivalent is `StateMachineDatabase.LoadStateMachineForImporter<T>`.
+- **Wrap every programmatic edit** in `UndoBeginRecordGraph` / `UndoEndRecordGraph` and call
+  `GraphDatabase.SaveGraph`. Never mutate the graph inside `OnEnable`, `OnDisable` or `OnGraphChanged`;
+  it throws `InvalidOperationException`.
+
+## Step 1
+
+Before you go forward with a workflow or diagnosis:
+
+1. Get the Editor version from the user's message, or else from `m_EditorVersion` in
+   `ProjectSettings/ProjectVersion.txt`, and pick the API from the table below. A version the user
+   names wins over a newer project. Ask only when neither gives it.
+2. Open and read the [documentation page(s)](#topic-map) that cover what you intend to do or fix. Where
+   the manual has no page, read the reference file named in [Step 3](#step-3-where-the-docs-stop).
+3. Name the file(s) you read in your response.
+
+A missing Unity project or unreachable docs do not block the answer: write the code from this skill
+and its references, say where each file goes, and name what you could not check.
+
+This is because your training knowledge about Unity might be out of date, incorrect, or for the wrong
+Unity version. Graph Toolkit changed significantly between 6000.4, 6000.6 and 6000.7.
+
+| Editor version | Available |
+|---|---|
+| Older than 6000.4 | Only the retired experimental package (0.x). Its API differs from this skill. Recommend upgrading. |
+| 6000.4 to 6000.5 | Module present, but without port capacity, type casting, wire and node visualization, USS node styling, or element IDs. |
+| 6000.6 | The Graph API. |
+| 6000.7 and newer | Everything above plus the State Machine API, `NodeView<T>` / `StateView<T>` / `ConditionView<T>` custom UI, `[GraphMenu]` / `[BlackboardMenu]` context menus, the `GraphLogger.GraphChanges` change delta, polymorphic and type-following ports, and Blackboard type restriction. |
+
+If the user asks for a state machine tool on an Editor older than 6000.7, say plainly that the State
+Machine API is not available there. Do not emulate it with the Graph API unless asked.
+
+## Step 2: Start from the graph tool skeleton
+
+The `implement-a-graph-tool.md` and `implement-nodes.md` pages explain this in full. When they cannot
+be fetched, start from:
+
+```csharp
+[Graph(AssetExtension)] [Serializable]                     // GraphOptions.SupportsSubgraphs as a second argument
+class DialogueGraph : Graph
+{
+    public const string AssetExtension = "dialogue";
+    [MenuItem("Assets/Create/Dialogue/Dialogue Graph")]
+    static void Create() => GraphDatabase.PromptInProjectBrowserToCreateNewAsset<DialogueGraph>();
+}
+
+[Serializable] [Node("Dialogue")]
+class LineNode : Node
+{
+    protected override void OnDefinePorts(IPortDefinitionContext context)
+    {
+        context.AddInputPort("In").Build();                                       // untyped: execution flow
+        context.AddInputPort<string>("Text").Build();
+        context.AddOutputPort("Next").WithCapacity(PortCapacity.Single).Build();  // outputs accept many wires by default
+    }
+}
+```
+
+Different port types do not connect unless `Graph.IsConnectionAllowed(IPort output, IPort input)`
+allows it; the graph only records the wire, and the importer does the conversion.
+
+### Gotchas
+
+| Symptom | Fix |
+|---|---|
+| A typed input port refuses a second wire, or an output accepts several | Typed inputs default to `PortCapacity.Single`; untyped ports and outputs to `Multi`. Set `WithCapacity` explicitly |
+| `GetInputPortByName` or `GetNodeOptionByName` returns the wrong element or null | Port and option names are lookup keys: keep them unique, share a `const` between `OnDefineOptions` and `OnDefinePorts` |
+| Ports rebuild on every keystroke of a count option | `.Delayed()` on the option |
+| `AsVertical()` has no effect | Block node ports are always horizontal |
+| A node lands in an odd Add-menu folder such as `Math/Add/Add` | The first `[Node]` argument is a folder path; the title is appended to it |
+| `OnEnable` runs several times | Expected on load, reopen and domain reload: keep it idempotent |
+| Compile error on a class marked `[SerializeReference]` | That attribute is for fields; classes take `[Serializable]` |
+
+## Step 3: Where the docs stop
+
+Read before writing importer, state machine or change-tracking code: these parts have no manual page, and the code shapes you need are in [where-the-docs-stop.md](references/where-the-docs-stop.md).
+
+## Topic map
+
+The docs are online at `https://docs.unity.com/en-us/engine/<VERSION>/`. Replace `<VERSION>` with the
+project's Editor version from `ProjectSettings/ProjectVersion.txt`, for example `6000.6` or `6000.7`.
+Pages are served as markdown when the `.md` suffix is kept. Prefer `WebFetch` over `WebSearch`; it is
+faster and lands on the exact page. Only fetch what you need.
+
+- **GTK index**: `manual/extending-the-editor/gtk-index.md`, the landing page for all GTK manual topics
+  - **Implementing a graph tool**: `manual/extending-the-editor/gtk-index/implementing-a-graph-tool.md`,
+    with these pages under it:
+    - `implement-a-graph-tool.md`: graph class, asset creation, menu item
+    - `implement-nodes.md`: node class, `OnDefinePorts`, discovery rules
+    - `implement-node-options.md`: `IOptionDefinitionContext`, `Delayed`, `ShowInInspectorOnly`
+    - `implement-context-nodes.md`: `ContextNode`, `BlockNode`, `UseWithContext`
+    - `implement-block-nodes.md`: block port rules, horizontal-only ports
+    - `type-cast-ports.md`: `IsConnectionAllowed`, cross-type connections
+    - `add-custom-toolbar-actions.md`: `GraphToolbarElement`, `IGraphWindow`
+    - `add-subgraph-support.md`: `GraphOptions.SupportsSubgraphs`, subgraph ports from Blackboard variables
+    - `graph-processing.md`: `OnGraphChanged`, `GraphLogger`, `GraphLogAction`, fix buttons
+  - **Graph window and panels**: `manual/extending-the-editor/gtk-index/landing-graph-interface.md`, with
+    `graph-window.md`, `blackboard.md`, `graph-inspector.md` and `minimap.md` under it
+  - **Debug graph view** (manual from `6000.7`; the API is the same on 6.6):
+    `manual/extending-the-editor/gtk-index/landing-implementing-debug-graph-view.md`, with
+    `concept-graph-visualization.md`, `task-display-node-progress.md`, `task-display-port-values.md`,
+    `task-display-errors-in-graph.md` and `task-customize-wire-display.md` under it
+- **Samples**: `https://docs.unity3d.com/Packages/com.unity.graphtoolkit-samples@<PKG_VERSION>/manual/index.html`.
+  Install `com.unity.graphtoolkit-samples` by name in the Package Manager, replace `<PKG_VERSION>` with
+  the version shown there, then import Texture Maker (importer), Visual Novel Director (runtime and live
+  debug view) or Dungeon Graph Generator (building a graph from code).
+- **Community**: `https://discussions.unity.com/tag/graph-toolkit`, for known issues and workarounds not
+  yet in the docs.
+
+### API reference
+
+Exact type names per API and how to build a Script Reference URL or read the local HTML copy: [api-reference.md](references/api-reference.md).
+
+## Final step
+
+Do the following checks:
+
+1. Check the project has zero console errors. Use `unity command console status` for counts. Without
+   the Unity CLI, ask the user to select the Editor and report what is displayed in the Console.
+2. Create an asset from the new menu item, add every node or state type from the Add menu, connect
+   them, save, close and reopen. The Console must show no errors or warnings. A type missing from the
+   Add menu is abstract, generic, or in another assembly without `[UseWithGraph]` /
+   `[UseWithStateMachine]`.
+3. With an importer, confirm the produced runtime object is the main asset.
+4. Stop there unless the user asked you to prove it works or you suspect a specific fault.
+5. If you do enter Play mode, do it once only to chase a fault you already suspect. Read the world
+   through `unity command script eval --caller plugin --skill build-gtk --code '<snippet>'` rather than adding logging. Take no screenshots as they take too
+   much time.
+
+If a check fails, go back and reread the [docs pages](#topic-map) or reference file for that step to
+find out what you missed.
+
+## Final report
+
+Give the user a concise but not dense checklist of what you did and why. If the user needs to follow up
+with more steps or decisions, list them. For example:
+
+```
+I made the following changes:
+
+[✓] Created `Editor/DialogueGraph.cs`: the graph class registered on the `.dlg` extension.
+[✓] Created `Editor/DialogueNode.cs`: a start node and a line node with text and next ports.
+[✓] Created `Editor/DialogueImporter.cs`: compiles the graph into a `DialogueRuntimeGraph` asset.
+
+To create your first graph:
+1. Right-click in the Project window > Create > Dialogue > Dialogue Graph.
+2. Double-click the asset to open the graph window.
+3. Add a Start node and a Line node from the Add menu and connect them.
+4. Save. The Inspector should show the compiled `DialogueRuntimeGraph` as the main asset.
+
+Still to decide:
+- More node types (choice branches, wait, end).
+- The runtime executor (a MonoBehaviour that walks the runtime asset).
+- A live debug view using the GraphVisualization API.
+```

package/skills/build-gtk/references/api-reference.md

@@ -0,0 +1,33 @@
+# API reference
+
+If the Editor install folder has a `Data/Documentation` folder (for example
+`.../Unity/Hub/Editor/6000.6.0f1/Editor/Data/Documentation`), read the HTML files in its
+`en/ScriptReference` folder. Otherwise the Script Reference is online:
+
+```
+https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unity/graphtoolkit/editor/<typename>.md
+```
+
+Type names are all lowercase with generic arity dropped (`condition.md` for `Condition<T>`). Member
+pages nest one level deeper: `.../graph/ongraphchanged.md`. The older HTML form also resolves:
+`https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/Unity.GraphToolkit.Editor.<Type>.html`.
+
+**Graph API (6.6+):** `Graph`, `GraphDatabase`, `GraphOptions`, `GraphLogger`, `GraphLogAction`,
+`GraphChanges` (6.7), `ChangedNode` (6.7), `ChangeKind` (6.7), `Node`, `NodeAttribute`, `NodeView<T>` (6.7), `IPort`, `IPortDefinitionContext`,
+`IInputPortBuilder`, `IOutputPortBuilder`, `PortCapacity`, `PortConnectorUI`, `PortDirection`,
+`INodeOption`, `IOptionDefinitionContext`, `ContextNode`, `BlockNode`, `UseWithContext`, `UseWithGraph`,
+`ISubgraphNode`, `Subgraph` (attribute), `IVariable`, `IVariableNode`, `VariableKind`, `IConstantNode`,
+`IGraphWindow`, `GraphToolbarElement`, `GraphMenu` (6.7), `BlackboardMenu` (6.7), `Wire`
+
+**State Machine API (6.7+):** `StateMachine`, `StateMachineDatabase`, `StateMachineOptions`,
+`StateMachineLogger`, `StateMachineLogAction`, `StateMachineChanges`, `State`, `StateAttribute`,
+`StateView<T>`, `IState`, `ITransition`, `ITransitionRule`, `ICondition`, `IGroupCondition`,
+`GroupConditionOperation`, `IVariableCondition`,
+`Condition`, `Condition<T>`, `ConditionAttribute`, `ConditionView<T>`, `ConditionComparison`,
+`SelfTransition`, `TransitionAttribute`, `ISubgraphState`, `StateMachineMenu`, `ConditionMenu`,
+`UseWithStateMachine`
+
+**GraphVisualization API (6.6+),** namespace `Unity.GraphToolkit.Editor.GraphVisualization`, pages
+under `.../graphvisualization/<typename>.md`: `Registry`, `Context`, `GraphMotion`, `NodeReference`,
+`PortReference`, `WireReference`, `StateReference` (6.7), `TransitionReference` (6.7),
+`ConditionReference` (6.7)

package/skills/build-gtk/references/graph-api-gaps.md

@@ -0,0 +1,96 @@
+# Graph API parts the manual does not cover yet
+
+The Graph Toolkit manual pages cover the 6.6 Graph API: graph and node classes, ports,
+options, context and block nodes, subgraphs, type casting, toolbar actions and `OnGraphChanged`. This
+file covers what they do not: the change delta, and the Unity 6000.7 additions. Members marked
+**6.7** do not exist on 6000.6. All types live in `Unity.GraphToolkit.Editor`; confirm any member not
+listed here in the Script Reference before using it.
+
+## Contents
+
+1. Knowing what changed
+2. Ports whose type is chosen or follows a connection (6.7)
+3. Blackboard types and variable nodes (6.7)
+4. Context menus (6.7)
+5. Custom node UI (6.7)
+
+## 1. Knowing what changed
+
+```csharp
+[NonSerialized] HashSet<Hash128> m_KnownNodes;
+
+public override void OnGraphChanged(GraphLogger logger)
+{
+    // 6.7 and newer: added and modified nodes.
+    foreach (var change in logger.GraphChanges.ChangedNodes)
+        if (change.Node is ObjectiveNode objective && (change.ChangeKinds & ChangeKind.Added) != 0) { /* new */ }
+
+    // Every version: removed nodes, and on 6.6 additions too, come from diffing IDs.
+    var current = new HashSet<Hash128>(GetNodes().Select(n => n.ID));
+    if (m_KnownNodes != null)
+        foreach (var removed in m_KnownNodes.Except(current)) { /* removed */ }
+    m_KnownNodes = current;
+}
+```
+
+- **6.7** `GraphLogger.GraphChanges` is the change delta. It does not exist on 6.6.
+- The delta lists added and modified elements only. Removed nodes, variables and subgraph nodes are
+  never reported; removed ports are, under `ChangedNode.ChangedPorts` with `ChangeKind.Removed`.
+- Members are in `graphchanges.md` and `changekind.md`. Each entry exposes its element by type,
+  for example `ChangedNode.Node`, plus `ChangeKinds` flags to test with `&`.
+- The ID cache is `[NonSerialized]` so it is not written to the asset, and it starts null after a
+  domain reload, so the first call only fills it.
+- Never mutate the graph in `OnGraphChanged`; it throws `InvalidOperationException`. Offer the fix as
+  a `GraphLogAction` on the message instead.
+
+## 2. Ports whose type is chosen or follows a connection (6.7)
+
+- `WithDataTypes(params Type[])` or `WithDataTypes(IEnumerable<Type>)` on an untyped port builder makes
+  a polymorphic port that accepts any of the listed types. At least one type; duplicates are ignored.
+  On 6.6, use an untyped port and allow the connections in `Graph.IsConnectionAllowed`.
+- `IPort.TrySetDataType(Type)` changes a port's type, and the override
+  `Node.OnPortDataTypeChanged(IPort port, Type previous, Type next)` reacts to it, for ports whose type
+  follows what they are connected to.
+- `Graph.UndoBeginRecordGraph(string actionName, params Node[] nodesToRecord)` records specific nodes.
+
+## 3. Blackboard types and variable nodes (6.7)
+
+- Restrict the Blackboard type dropdown by overriding
+  `protected virtual IEnumerable<Type> BuildAvailableVariableTypes(IReadOnlyCollection<Type> baseSupportedTypes)`
+  and `BuildAvailableConstantTypes(...)` on the graph. `Graph.SupportedTypes`, `AvailableVariableTypes`
+  and `AvailableConstantTypes` list the result. On 6.6 the type list is not customizable. A
+  `StateMachine` overrides the parameterless `BuildAvailableVariableTypes()` and has no constant types.
+- `Graph.AddVariableNode(IVariable, Vector2, VariableNodeMode)` with `VariableNodeMode.Get` or `Set`,
+  read back through `IVariableNode.Mode`.
+
+## 4. Context menus (6.7)
+
+```csharp
+[GraphMenu(typeof(MyGraph))]
+static void AddGraphMenuEntries(GraphMenuContext context)
+{
+    if (context.ClickedObject is INode node)
+        context.AppendAction("Inspect node", () => Debug.Log(node.Title));
+    context.AppendSeparator();
+}
+```
+
+The context has `object ClickedObject`, `Vector2 MousePosition`, `AppendAction(name, Action)`,
+`AppendAction(name, Action<DropdownMenuAction>[, status callback])` and `AppendSeparator(subMenuPath)`.
+`[BlackboardMenu(typeof(MyGraph))]` receives the same context for the Blackboard. State machine menus
+are in `state-machine-api.md`.
+
+## 5. Custom node UI (6.7)
+
+`class MyNodeView : NodeView<MyNode>` adds UI Toolkit elements to a node. Discovery is by the generic
+argument, walking up the node's inheritance chain. On 6.6 the only styling is USS through
+`[Node(category, icon, title, stylesheet)]`, `Node.DefaultColor` and `Node.FillAmount`.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Duplicated labels or buttons pile up on the node | UI allocated in `OnViewAttached`, which fires on every re-attach | Allocate in `OnViewBuilt`, cache, append to `View.Root` |
+| The custom element disappears after zooming far out and back | Culling clears `Root` | Re-add the cached element in `OnCullingChanged(false)` |
+
+Also available: `OnViewDetached()`, `OnViewLODChanged(float zoom)`. The same rules apply to
+`StateView<T>`. `ConditionView<T>` has no LOD or culling callbacks: `OnViewBuilt`, `OnViewAttached`,
+`OnViewDetached` and `OnConditionChanged` only.