cue-ai 0.9.0 → 0.9.2

package/resources/skills/skills/meta/verify-council/references/workflow.js

@@ -0,0 +1,217 @@
+export const meta = {
+  name: 'verify-council',
+  description: 'Token-scaled council of independent verifier lanes plus a real-screen visual lane; returns raw verdicts for the author to adjudicate.',
+  phases: [
+    { title: 'Council', detail: 'parallel verifier lanes over the diff + claims' },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// args (all passed by the orchestrating agent — scripts have no FS access):
+//   diff          string   capped unified diff of the change (inline)
+//   diffCmd       string   OR a scoped command the lane runs to get the diff,
+//                          e.g. "git diff -- src/lib/picker.ts". Use this
+//                          instead of `diff` for large diffs — same token cost,
+//                          no giant string through args. One of diff/diffCmd.
+//   claims        array    [{ id, text, kind: 'logic'|'visual', file }]
+//   surface       string   'code' | 'tui' | 'web'   (default 'code')
+//   hardToReverse boolean  add the skeptic lane when true
+//   appCmd        string   how the visual lane launches a TUI surface (optional)
+//   url           string   dev-server URL for a web surface (optional)
+//
+// The MECHANICAL gate (tests / typecheck / lint) runs in the orchestrator
+// BEFORE this script — a failing gate means no council is spawned at all. This
+// engine is only the agent fan-out; adjudication happens back in the orchestrator
+// on the strong model, so the strong model never enters the parallel barrier.
+// ---------------------------------------------------------------------------
+
+// The harness may hand `args` to the script as a JSON STRING rather than a parsed
+// object (verified: typeof args === 'string'). Parse it so a.claims / a.diff /
+// a.hardToReverse resolve — otherwise every field reads undefined and the lanes
+// run with no diff and no claims, which makes them roam the whole repo.
+let a = args ?? {}
+if (typeof a === 'string') {
+  try { a = JSON.parse(a) } catch { a = {} }
+}
+const diff = String(a.diff ?? '').slice(0, 60000)
+const diffCmd = a.diffCmd ? String(a.diffCmd) : ''
+const claims = Array.isArray(a.claims) ? a.claims : []
+const surface = a.surface ?? 'code'
+const isVisual = surface === 'tui' || surface === 'web'
+
+// Each lane either gets the diff inline, or is told to run one scoped command to
+// obtain it (kept scoped so the lane never roams the repo — the token discipline
+// is the same either way).
+const diffSection = diff
+  ? `The change under review is EXACTLY the diff below. Do not read or report on any
+file outside it; discard any issue you cannot tie to a line shown here.
+--- DIFF ---\n${diff}\n--- END DIFF ---`
+  : diffCmd
+    ? `The change under review is EXACTLY the output of this one command. Run it
+verbatim and treat its output as the complete and only changeset:
+  ${diffCmd}
+Hard scope: do NOT run \`git diff\` without these exact paths, do NOT open, read,
+or report on any file outside this output, and discard any finding you cannot
+tie to a line inside it. Reviewing the wider repo is a scope violation that wastes
+the token budget.`
+    : '(no diff provided — audit the claims against the named files only)'
+
+// When the caller lists claims, the lane must answer THOSE claims, not invent its
+// own. Without this the lane drifts into a free-form repo review (more tokens, and
+// the caller's actual claims go unverified).
+const claimsDirective = claims.length
+  ? `Return exactly one verdict per claim id below, using these ids verbatim. Do not
+add, rename, merge, or invent claim ids. If a claim cannot be judged from the
+changeset, mark it NA with that reason.`
+  : `No claims were listed: derive the key correctness claims from the changeset itself.`
+
+const claimsBlock = claims.length
+  ? claims.map((c, i) => `${c.id ?? i + 1}. [${c.kind ?? 'logic'}] ${c.text}${c.file ? `  (${c.file})` : ''}`).join('\n')
+  : '(no explicit claims listed — audit the diff for correctness)'
+
+// Structured verdict every lane returns, so the orchestrator never parses prose.
+const VERDICT = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['lane', 'summary', 'claims', 'findings'],
+  properties: {
+    lane: { type: 'string' },
+    summary: { type: 'string', description: 'one line' },
+    claims: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['id', 'verdict', 'evidence'],
+        properties: {
+          id: { type: 'string' },
+          verdict: { type: 'string', enum: ['PASS', 'FAIL', 'PARTIAL', 'NA'] },
+          evidence: { type: 'string', description: 'quoted line or measured value — never a paraphrase' },
+        },
+      },
+    },
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['severity', 'text'],
+        properties: {
+          severity: { type: 'string', enum: ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'] },
+          text: { type: 'string' },
+        },
+      },
+    },
+  },
+}
+
+const NEUTRAL = `You are an INDEPENDENT verifier with no shared context. Do not edit anything.
+Several assertions below may be false — do not assume they are correct.
+For each claim return verdict PASS/FAIL/PARTIAL/NA with evidence that QUOTES the
+exact line or MEASURES the value. A remembered or paraphrased line is not evidence.`
+
+function correctnessPrompt() {
+  return `${NEUTRAL}
+
+Lane: correctness. Re-derive each claim strictly from the change.
+${claimsDirective}
+
+CLAIMS:
+${claimsBlock}
+
+${diffSection}`
+}
+
+function redteamPrompt() {
+  return `${NEUTRAL}
+
+Lane: red-team. Review ONLY the change for blocking defects.
+  CRITICAL: security holes, data loss, crashes, injection, broken auth.
+  HIGH:     real bugs, broken contracts, race conditions, wrong logic.
+List each as a finding with its severity. Do not list LOW/style nits as blocking.
+If there are no CRITICAL or HIGH defects, return an empty findings array and
+summary "REVIEW_CLEAN". Map each claim's verdict to NA unless the change disproves it.
+
+${diffSection}`
+}
+
+function visualPrompt() {
+  const visualClaims = claims.filter((c) => c.kind === 'visual')
+  const vBlock = visualClaims.length
+    ? visualClaims.map((c, i) => `${c.id ?? i + 1}. ${c.text}`).join('\n')
+    : '(measure whatever the diff claims about the rendered surface)'
+  const driver = surface === 'web'
+    ? `Surface: WEB. Use the lightpanda MCP tools (search for them with ToolSearch:
+   goto ${a.url ?? '<dev-server-url>'} , then eval getComputedStyle() /
+   getBoundingClientRect() on the relevant selectors and return the MEASURED
+   pixel values.`
+    : `Surface: TUI. Use the cue-tty-watch MCP tools (search for them with ToolSearch):
+   launch the app in a tmux pane${a.appCmd ? ` with \`${a.appCmd}\`` : ''}, send_keys_tmux to
+   reach the target screen, screenshot it, then find_text / ask_about_image to
+   assert each claim against what is ACTUALLY on screen.`
+
+  return `${NEUTRAL}
+
+Lane: visual proof. Drive the REAL rendered surface and report what you observe.
+A code read is NOT acceptable evidence for a visual claim — only a measured or
+screenshotted value counts.
+
+${driver}
+
+VISUAL CLAIMS:
+${vBlock}`
+}
+
+function skepticPrompt() {
+  return `${NEUTRAL}
+
+Lane: skeptic. Your job is to REFUTE the riskiest claim, not confirm it. Default
+each claim to FAIL ("refuted") unless the change makes it undeniable. Be adversarial.
+${claimsDirective}
+
+CLAIMS:
+${claimsBlock}
+
+${diffSection}`
+}
+
+// Adaptive lane set: 2 default, +visual when visual, +skeptic when hard to reverse.
+const lanes = [
+  { key: 'correctness', prompt: correctnessPrompt() },
+  { key: 'redteam', prompt: redteamPrompt() },
+]
+if (isVisual) lanes.push({ key: 'visual', prompt: visualPrompt() })
+if (a.hardToReverse) lanes.push({ key: 'skeptic', prompt: skepticPrompt() })
+
+// Surface the parsed inputs so a misdelivery (e.g. empty claims, no diff) is
+// obvious in the run log instead of silently degrading into a repo-wide roam.
+log(
+  `council: ${lanes.map((l) => l.key).join(' + ')} ` +
+    `(surface=${surface}, claims=${claims.length}, diff=${diff ? 'inline' : diffCmd ? 'cmd' : 'NONE'})`,
+)
+
+phase('Council')
+const verdicts = await parallel(
+  lanes.map((l) => () =>
+    agent(l.prompt, { label: `lane:${l.key}`, phase: 'Council', schema: VERDICT, model: 'sonnet' })
+      .then((v) => ({ ...v, lane: l.key }))
+  ),
+)
+
+const ok = verdicts.filter(Boolean)
+const blocking = ok.flatMap((v) =>
+  (v.findings ?? []).filter((f) => f.severity === 'CRITICAL' || f.severity === 'HIGH').map((f) => ({ lane: v.lane, ...f })),
+)
+const failed = ok.flatMap((v) =>
+  (v.claims ?? []).filter((c) => c.verdict === 'FAIL' || c.verdict === 'PARTIAL').map((c) => ({ lane: v.lane, ...c })),
+)
+
+// Raw material for the orchestrator's Phase-2 adjudication. No strong-model
+// spend happened inside this script.
+return {
+  lanes: lanes.map((l) => l.key),
+  verdicts: ok,
+  blocking,
+  disputedClaims: failed,
+  clean: blocking.length === 0 && failed.length === 0,
+}

package/resources/skills/skills/nvidia/aiq-research/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "When user asks for deep research, multi-source synthesis, regulatory analysis, or enterprise document research, route through AI-Q server for structured reports with citations"
+description: "Use when user says \"deep research this\", \"research the regulatory landscape\", \"synthesize findings from our docs\", \"produce a cited memo\", \"multi-source research\". Routes deep research, multi-source synthesis, regulatory analysis, or enterprise document research through the NVIDIA AI-Q server for structured reports with citations."
 tags: [research, nvidia, aiq, deep-research, enterprise]
 category: nvidia
 version: 2.0.0

package/resources/skills/skills/nvidia/cuopt-developer/SKILL.md

@@ -3,7 +3,6 @@ name: cuopt-developer
 version: "26.08.00"
 description: Modify, build, test, debug, and contribute to NVIDIA cuOpt (C++/CUDA, Python, server, CI). Use for solver internals, PRs, DCO, and code conventions.
 ---
-
 # cuOpt Developer Skill
 
 Contribute to the NVIDIA cuOpt codebase. This skill is for modifying cuOpt itself, not for using it.
@@ -232,3 +231,19 @@ For build/test pitfalls (Cython rebuild, OOM, CUDA driver mismatch, missing `nvc
 - **Python binding architecture**: [resources/python_bindings.md](resources/python_bindings.md)
 
 _Shell-execution, install, sudo, and outside-workspace policies are covered by [Refusal Rules — Read First](#refusal-rules--read-first) at the top of this skill._
+
+## VRP dimension internals (routing engine)
+
+When implementing or debugging **VRP dimensions** (constraints, objectives, forward/backward propagation, `combine`, local-search deltas), read:
+
+- **`resources/vrp_skills.md`** — architecture contracts, required interfaces, and implementation checklist.
+
+Read it **before** adding a new dimension or changing combine semantics.
+
+## Numerical issues in non-routing solver internals
+
+When a bug surfaces as **wrong-but-plausible** solver output (invalid lower bound, unexpectedly large duals, 10× iteration blow-up after a small change) rather than a crash, read:
+
+- **`resources/numerical_debugging.md`** — methodology for locating catastrophic-cancellation sites, the cancellation patterns endemic to cMIR / flow-cover / MIR-style cut construction, and threshold guidance for numerical guards.
+
+Apply the *instrument-first, guard-at-the-exact-site* workflow it describes before patching — speculative fixes on these symptoms usually miss.

package/resources/skills/skills/nvidia/cuopt-developer/resources/contributing.md

@@ -32,11 +32,11 @@ Never push branches directly to the main cuOpt repository. Use the fork workflow
 
 ```bash
 # 1. Clone the main repo
-git clone git@github.com:NVIDIA/cuopt.git
+git clone https://github.com/NVIDIA/cuopt.git
 cd cuopt
 
 # 2. Add your fork as a remote
-git remote add fork git@github.com:<your-username>/cuopt.git
+git remote add fork https://github.com/<your-username>/cuopt.git
 
 # 3. Create a branch from the appropriate base
 git checkout -b my-feature-branch

package/resources/skills/skills/nvidia/cuopt-developer/resources/numerical_debugging.md

@@ -0,0 +1,128 @@
+# Debugging Numerical Issues in Numerical Optimization Solver Internals
+
+Read this when a solver bug surfaces as **wrong-but-plausible output** rather
+than a crash or assertion.
+
+## Symptoms
+
+- A lower bound that contradicts a known incumbent (LP claims a value the MIP
+  cannot reach).
+- Dual values of order `1e10+` on a problem whose data is `O(1)`–`O(1e5)`.
+- A 10× blow-up in simplex iterations after an algorithmic change that should
+  have been cheap.
+- Bit-for-bit reproducibility of the wrong answer across runs — the bug is
+  deterministic, not a memory or race issue.
+
+The root cause is often **catastrophic cancellation** in a
+floating-point accumulator: `final = Σ(signed contributions)` collapses to a
+value many orders of magnitude smaller than its constituents, leaving the
+result dominated by floating-point noise.
+
+## Methodology — Instrument Before Patching
+
+The classical mistake is to guess the cancellation site and apply a fix. There
+are usually several candidates and you will guess wrong. Do this instead:
+
+### Locate the suspicious region
+
+Usually a recent commit or a code path tied to the symptom. Read it end-to-end before adding any instrumentation.
+
+### Audit candidate cancellation sites by hand
+
+Any floating-point accumulator whose result can be much smaller than its inputs is a candidate.
+Write the list down before you instrument anything.
+
+### Instrument each site with a `cancel_ratio = |final| / max(1, Σ|delta|)`
+
+Logged per event. A ratio of `1.0` means no cancellation; `1e-9` means ~7 decimal digits of precision lost; `1e-15` means the result is numerical noise.
+
+### Reproduce, log, read
+
+Sort the log by `cancel_ratio` ascending; the worst offenders are at the top.
+
+### Guard at the exact site that's cancelling — not earlier, not later
+
+A guard on an upstream accumulator does nothing if cancellation happens downstream; cut-generation paths typically have multiple sites in series.
+
+### Re-run and confirm
+
+If the symptom persists, your instrumentation missed a site — return to step 2. The cancellation hypothesis is wrong only if every measured ratio is `≥ ~1e-6` and the symptom is still there.
+
+## Threshold Guidance
+
+A cancellation ratio of `1e-9` leaves ~7 decimal digits of precision in a
+double. Use this as the *machine-safety* floor — a guard at this level only
+rejects results that are essentially noise.
+
+A ratio of `1e-4` leaves ~12 digits, which is still numerically clean but
+tight enough that downstream LP solves remain conditioned. Use this for guards
+on quantities that feed back into a basis whose conditioning matters (cut
+RHS, constraint accumulators, anything that becomes a row of `A` after
+addition).
+
+When in doubt, log the ratio *without* filtering first, observe the
+distribution across a representative benchmark, and place the threshold at
+least one order of magnitude below the cleanest "bad" case and at least one
+order of magnitude above the cleanest "good" case. Single-instance threshold
+choices tend to over-fit.
+
+## Cancellation Sites in Cut Generation
+
+Cut-generation routines (Gomory, MIR, complemented-MIR, flow-cover) are
+repeat offenders. They build a cut by combining row data with variable-bound
+substitutions, each of which can introduce a large
+`coefficient × bound_bias` shift. The shifts often sum to a small residual.
+
+In a cMIR-style routine, expect **three accumulators in series**, each
+capable of independent cancellation:
+
+| # | Accumulator | Cancellation form |
+|---|---|---|
+| 1 | Substituted row RHS | `b − Σ (coef × variable_bound_bias)` |
+| 2 | Cut-LHS constant | `Σ (multiplier × per_arc_constant)` across all arcs |
+| 3 | Final cut RHS subtraction | `cut.rhs = lhs_constant − substituted_b` |
+
+Two of the three can have well-behaved ratios individually while the third
+still cancels — site (3) is especially insidious because both inputs can be
+clean on their own and only their *difference* loses precision. A guard at
+only one site is insufficient; instrument all three before deciding where to
+clamp.
+
+## Scale-Mismatch Hazard
+
+A cut that is mathematically valid by construction can still poison the LP
+basis after addition. If `cut.rhs` is several orders of magnitude below the
+original constraint matrix's typical row scale, the dual simplex needs to
+produce dual values at the inverse scale to express dual feasibility, and
+those duals propagate into the bound.
+
+The diagnostic for this is **iteration count**, not the cut shape.
+Re-optimization after cut addition should take `O(few ×)` the original root
+iterations. If it suddenly takes `O(10×)`, the cuts are valid but
+ill-conditioned for the LP.
+
+Filters that help, in order of increasing aggressiveness:
+
+- Reject cuts with high coefficient dynamism (`max|coef| / min|coef|`).
+- Reject cuts with `|cut.rhs|` much smaller than the original row scale on
+  the source row.
+- Suppress variable-bound substitutions whose bias term is itself huge —
+  root-cause filter, but rejects more cuts than necessary.
+
+Pick the lowest-risk filter that removes the symptom on the failing instance.
+Re-validate on the broader benchmark before declaring the fix done — a guard
+that fixes one instance can quietly suppress healthy cuts on others.
+
+## Common Mistakes
+
+- **Speculative fix before measurement.** "It's probably the MIR floor at
+  large ratios" is a guess. Instrument first; the data usually points
+  elsewhere.
+- **Single global guard.** A guard at the first cancellation site won't catch
+  the rest. Cut paths typically have 2–3 distinct sites in series.
+- **Confusing "small final value" with "cancellation."** A small `final`
+  derived from a small sum of small `delta_i` is healthy. The ratio
+  `|final| / Σ|delta_i|` is what distinguishes the two.
+- **Picking the most aggressive (root-cause) filter when a narrow site-guard
+  would do.** Be surgical; the narrowest filter that recovers correctness is
+  the right one.

package/resources/skills/skills/nvidia/cuopt-developer/resources/python_bindings.md

@@ -106,6 +106,8 @@ def Solve(py_data_model_obj, settings, mip=False):
     return create_solution(move(sol_ret_ptr), data_model_obj)
 ```
 
+Always release the GIL around C++ calls that do GPU work — this allows other Python threads to run during solve.
+
 ### Step 6: C++ implementation receives the call
 
 `cpp/src/math_optimization/solver_settings.cu`:
@@ -145,15 +147,6 @@ settings.reset(new solver_settings_t[int, double]())
 # Auto-destroyed when scope exits
 ```
 
-### Releasing the GIL for GPU work
-
-```cython
-with nogil:
-    result = move(call_solve(problem_ptr, settings_ptr))
-```
-
-Always release the GIL around C++ calls that do GPU work. This allows other Python threads to run during solve.
-
 ### Bridging C++ enums to Python IntEnum
 
 ```python

package/resources/skills/skills/nvidia/cuopt-developer/resources/vrp_skills.md

@@ -0,0 +1,166 @@
+# cuOpt VRP Dimension Developer Skills
+
+---
+
+## `cuopt-dimension-architecture`
+
+**When to use**: Before implementing any new constraint or objective in cuOpt.
+
+### The forward/backward propagation model
+Each node stores accumulated state (`fwd_X`, `bwd_X`) so that combining any two adjacent fragments is O(1). This is the core design contract that makes cuOpt fast:
+- `fwd_X[k]` = contribution of the prefix `[0..k]`
+- `bwd_X[k]` = contribution of the suffix `[k..n]`
+- No recomputation is needed when a move splits a route at any point
+
+### The combine invariant
+`combine(node[k], node[k+1])` must return the **same value for every split point `k`** in a route (within floating-point tolerance — small differences from order of operations are acceptable; large gaps indicate a bug). This is the fundamental correctness contract. Violating it breaks local search delta evaluation (the solver computes `cost_after - cost_before` using combine; if combine is materially inconsistent, deltas are wrong).
+
+### Why boundaries double-count
+`fwd_excess[k]` accumulates violations from `[0..k]`. `bwd_excess[k+1]` accumulates violations from `[k+1..n]`. At the join point `k → k+1`, both sides have already "seen" the in-transit state at that boundary — so their sum overcounts the boundary contribution once. The correction term `excess(fwd_state[k])` subtracts the double-counted boundary:
+```
+combine(k, k+1) = fwd_excess[k] + bwd_excess[k+1] - excess(fwd_state[k])
+```
+
+### Required interface for every dimension
+| Method | Description |
+|--------|-------------|
+| `calculate_forward(next)` | Propagate fwd state from `this` to `next`; update `next.fwd_excess` |
+| `calculate_backward(prev)` | Propagate bwd state from `this` to `prev`; update `prev.bwd_excess` |
+| `combine(prev, next)` | O(1) total cost for joining two fragments; must satisfy the invariant |
+| `get_cost(prev, this)` | Same formula as `combine`, called from `next`'s perspective |
+| `compute_cost(n_nodes)` | Full-route cost; must equal `combine(last_node, return_depot)` |
+| `forward_excess` | Returns `fwd_excess` as double |
+| `backward_excess` | Returns `bwd_excess` as double |
+| `forward_feasible` | True if `fwd_excess <= excess_limit` |
+| `backward_feasible` | True if `bwd_excess <= excess_limit` |
+
+---
+
+## `cuopt-implement-dimension`
+
+**When to use**: When given a constraint/objective description to implement as a new cuOpt dimension.
+
+### Step-by-step recipe
+
+**Step 1 — Define per-node state**
+Identify the minimal set of scalars needed for O(1) propagation:
+- What is "in transit" at each route position? (e.g. load, type counts, time)
+- What accumulated violation measure can be updated incrementally? (e.g. excess load, incompatibility excess)
+- Separate: *fixed data* (set once from problem input), *forward data*, *backward data*
+
+**Step 2 — Write `calculate_forward(next)`**
+```
+propagate accumulated fwd_state from this → next
+apply next node's demand to fwd_state
+compute positional_excess = f(fwd_state_at_next)
+next.fwd_excess = this.fwd_excess + positional_excess   // depot nodes: no positional contribution
+```
+
+**Step 3 — Write `calculate_backward(prev)`**
+Mirror of forward, applied in reverse direction. Backward demand direction is opposite to forward (e.g. a pickup that adds +1 forward subtracts -1 backward).
+
+**Step 4 — Derive `combine(prev, next)`**
+
+`combine` is the **core cost computation for every local search move**: operators evaluate candidate edits by differencing combined fragment costs (`cost_after - cost_before`). It is called extremely often, so **keep it as fast as possible**.
+
+- **Typical dimensions** (capacity, distance, simple time windows, etc.): `combine` is **O(1)** — only prefix/suffix scalars and a boundary correction. This is what all current VRP operators assume.
+- **Richer dimensions** can be **much more expensive** — e.g. **O(log n)** in route size `n` when the join cost needs a non-trivial lookup (time-dependent travel times, multiple time windows, profile queries). Prefer precomputed tables or cached state so `combine` stays hot-path friendly; if it must be superlinear, document it and expect fewer applicable operators or higher move-evaluation cost.
+
+Write out the invariant formula and verify it equals the total route cost for a complete route:
+```
+total = prev.fwd_excess + next.bwd_excess - boundary_correction(prev.fwd_state)
+```
+where `boundary_correction` removes the double-counted overlap at the join point.
+
+**Step 5 — Derive `get_cost(prev, this)` from combine**
+
+`get_cost` is on the **same hot path as `combine`**: local search operators call it constantly when scoring edges and fragments. It must stay **as fast as `combine`** — same **O(1)** target for typical dimensions, same risk of **O(log n)** or worse for time-dependent travel, multiple time windows, etc. **Do not** put a separate heavy computation here.
+
+`get_cost` is called on the `next` node with `prev` passed in. It must be identical to `combine` — substitute `this` for `next`:
+```
+get_cost(prev, this) == combine(prev, this)
+```
+Implement by **delegating to `combine`** (or inlining the same formula). Do **not** derive an independent formula; any deviation breaks coherence assertions and can hide a slower code path.
+
+**Step 6 — Write `compute_cost(n_nodes)`**
+Must equal `combine(last_service_node, fresh_return_depot)` within the same floating-point tolerance:
+```
+compute_cost = fwd_excess[n_nodes] - boundary_correction(fwd_state[n_nodes])
+```
+(For a balanced route, `bwd_excess` at the return depot is 0 and `bwd_state` is 0, so the depot term drops out.)
+
+**Step 7 — Create the node class**
+File: `cpp/src/routing/node/your_node.cuh`
+- Fixed data fields (problem input)
+- `fwd_state[]`, `fwd_excess`, `bwd_state[]`, `bwd_excess`
+- All 9 interface methods listed in `cuopt-dimension-architecture`
+
+**Step 8 — Create the route class**
+File: `cpp/src/routing/route/your_route.cuh`
+- Host-side: `rmm::device_uvector` for each array (fixed, fwd, bwd)
+- Device-side `view_t`: `raft::device_span` members, `get_node`, `set_node`, `set_forward_data`, `set_backward_data`, `copy_forward_data`, `copy_backward_data`, `copy_fixed_route_data`, `compute_cost`, `create_shared_route`, `get_shared_size`
+- Stride layout: all arrays use `stride = n_nodes_route + 1`; multi-type arrays are row-major `[n_types * stride]`
+
+---
+
+## `cuopt-dimension-wiring-checklist`
+
+**When to use**: After writing node/route logic, to ensure the dimension is fully integrated into the framework.
+
+### Files to create
+- [ ] `cpp/src/routing/node/your_node.cuh`
+- [ ] `cpp/src/routing/route/your_route.cuh`
+
+### Files to modify
+
+**`cpp/src/routing/routing_helpers.cuh`** (or `dimensions_info`)
+- [ ] Add new `dim_t` enum value
+- [ ] `enabled_dimensions_t::has_dimension` covers it
+- [ ] `enabled_dimensions_t::get_dimension<dim>` covers it
+- [ ] `loop_over_dimensions` range covers it (check `Start`/`End` bounds)
+
+**`cpp/src/routing/route/dimensions_route.cuh`**
+- [ ] Add to `route_from_dim<I>` type alias chain
+- [ ] Add member `your_route_t<i_t, f_t> your_dim` to `dimensions_route_t`
+- [ ] Initialize in constructor: `your_dim(sol_handle_, dimensions_info_.get_dimension<dim_t::YOUR_DIM>())`
+- [ ] Copy constructor copies `your_dim`
+- [ ] `view_t` has `typename your_route_t<i_t, f_t>::view_t your_dim` member
+- [ ] `view()` calls `get_dimension_of<I>(v) = get_dimension_of<I>(*this).view()` via loop — automatic if wired into enum
+
+**`cpp/src/routing/node/node.cuh`**
+- [ ] `get_dimension<dim_t::YOUR_DIM>()` returns `your_dim` member — add to the accessor chain
+
+**`cpp/src/routing/problem/problem.cuh`**
+- [ ] Add storage for input data (e.g. `std::vector<int> order_incompatible_types`)
+- [ ] Add setter method
+
+**`cpp/src/routing/problem/problem.cu`**
+- [ ] `populate_dimensions_info()`: enable dimension when input data is non-empty
+
+**`cpp/src/routing/util_kernels/set_nodes_data.cuh`**
+- [ ] Depot boundary initialization in `set_route_data`: set `fwd_state[0] = 0`, `fwd_excess[0] = 0`, `bwd_state[n_nodes] = 0`, `bwd_excess[n_nodes] = 0`
+
+**`cpp/src/routing/fleet_info.hpp`** (if dimension has vehicle-level parameters)
+- [ ] Add vehicle-level constraint data
+
+**Python/C API**
+- [ ] Expose setter in C API header
+- [ ] Python binding in the routing data class
+
+---
+
+## `cuopt-dimension-testing`
+
+**When to use**: After implementing a new dimension, to write tests that validate correctness end-to-end.
+
+### C++ unit tests (`cpp/tests/routing/`)
+- Add a simple unit test with less than 10 nodes/orders
+
+### Python integration tests (`python/cuopt/cuopt/tests/routing/`)
+- Add a similar test in python to test the Python APIs and end-to-end testing
+
+### What every test should verify
+- `is_feasible()` for the final solution when feasibility is expected
+- Infeasibility cost for the new dimension is 0 in a feasible solution
+- Optimal objective value is obtained for curated tests
+- Edge cases: empty route, single-node route, all nodes same type/value

package/resources/skills/skills/nvidia/cuopt-install/SKILL.md

@@ -3,7 +3,6 @@ name: cuopt-install
 version: "26.08.00"
 description: Install cuOpt for Python, C, or as a server (pip, conda, Docker) — system requirements, install commands, and verification. Use when the user wants to install or verify cuOpt for any user-facing interface. For building cuOpt from source or contributing to cuOpt, see cuopt-developer.
 ---
-
 # cuOpt Install (user)
 
 Install cuOpt to *use* it from Python, C, or as a REST server. For building cuOpt from source to contribute or modify it, see `cuopt-developer`.
@@ -77,15 +76,8 @@ conda install -c rapidsai -c conda-forge -c nvidia libcuopt
 
 ### Verify
 
-```bash
-# conda:
-find $CONDA_PREFIX -name "cuopt_c.h"
-find $CONDA_PREFIX -name "libcuopt.so"
-
-# pip (venv):
-find "$(python -c 'import sys; print(sys.prefix)')" -name "cuopt_c.h"
-find "$(python -c 'import sys; print(sys.prefix)')" -name "libcuopt.so"
-```
+See [`resources/verification_examples.md`](resources/verification_examples.md)
+for the canonical C-API header/library `find` commands (conda and pip/venv variants).
 
 ## Server (REST)
 

package/resources/skills/skills/nvidia/cuopt-numerical-optimization-api-c/SKILL.md

@@ -4,7 +4,6 @@ version: "26.08.00"
 description: LP, MILP, and QP (beta) with cuOpt — C API only. Use when the user is embedding LP, MILP, or QP in C/C++.
 ---
 
-
 # cuOpt Numerical Optimization — C API
 
 Solve LP, MILP, and QP problems via the cuOpt C API. The same library, headers, build pattern, and core calls (`cuOptCreate*Problem`, `cuOptSolve`, `cuOptGetObjectiveValue`) apply across all three; QP extends the API with quadratic-objective creation calls.
@@ -13,28 +12,9 @@ Confirm problem type and formulation (variables, objective, constraints, variabl
 
 This skill is **C only**.
 
-## Quick Reference: C API
-
-```c
-#include <cuopt/linear_programming/cuopt_c.h>
-
-// CSR format for constraints
-cuopt_int_t row_offsets[] = {0, 2, 4};
-cuopt_int_t col_indices[] = {0, 1, 0, 1};
-cuopt_float_t values[] = {2.0, 3.0, 4.0, 2.0};
-char var_types[] = {CUOPT_CONTINUOUS, CUOPT_INTEGER};
-
-cuOptCreateRangedProblem(
-    num_constraints, num_variables, CUOPT_MINIMIZE,
-    0.0, objective_coefficients,
-    row_offsets, col_indices, values,
-    constraint_lower, constraint_upper,
-    var_lower, var_upper, var_types,
-    &problem
-);
-cuOptSolve(problem, settings, &solution);
-cuOptGetObjectiveValue(solution, &obj_value);
-```
+## API Call Sequence
+
+For LP/MILP, the ordered C entry points are: `cuOptCreateRangedProblem` (sense `CUOPT_MINIMIZE` / `CUOPT_MAXIMIZE`, CSR constraint matrix as `row_offsets` / `col_indices` / `values`, `var_types` char array using `CUOPT_CONTINUOUS` / `CUOPT_INTEGER` macros) → `cuOptSolve(problem, settings, &solution)` → `cuOptGetObjectiveValue(solution, &obj_value)` → matching `cuOptDestroy*` calls. Include `<cuopt/linear_programming/cuopt_c.h>`. Full ordered code with build instructions in [resources/examples.md](resources/examples.md).
 
 ## QP via C API (beta)