skills: move and update BrainX install skill

[Wilsonnijc-bot]

Summary

• move brainx-install from docs/skills to the repository-level skills directory, parallel to docs
• update installation and release-selection guidance from the latest skill bundle
• add the uninstall and cleanup workflow reference

This supersedes the layout introduced by merged PR #118.

Verification

• confirmed the root-level skill matches the source bundle byte-for-byte
• passed the official skill validator
• confirmed the diff contains only the BrainX install skill relocation and update

Summary by Sourcery

Relocate and expand the BrainX install skill to support both installation and uninstall/cleanup workflows with stricter release selection and environment-handling rules.

New Features:

• Introduce a dedicated BrainX uninstall and cleanup reference that defines precise removal scope, safety rules, and verification steps.

Enhancements:

• Move the BrainX install skill from the docs subtree into the top-level skills directory for repository-wide usage.
• Update the BrainX install skill to handle uninstall routing, require explicit use of the compatibility matrix for pinned or existing installs, and tighten guidance on latest-release resolution and environment reuse.
• Clarify compatibility-matrix usage and refine version constraints in the BrainX release table to better reflect supported BrainUnit versions.

Documentation:

• Document the BrainX uninstall workflow, including environment inspection, optional JAX cleanup, confirmation gates, and reporting expectations.

[sourcery-ai]

Reviewer's Guide

Relocates the BrainX install skill from docs into the top-level skills directory while updating its workflow to handle explicit uninstall/cleanup routing, stricter release selection using compatibility metadata, and clearer environment and package-scoping rules, plus tightening the BrainX compatibility matrix constraints.

Flow diagram for updated BrainX install/uninstall skill routing

flowchart TD
  A[User BrainX request] --> B{Request type}

  B -->|uninstall / remove / cleanup| C[Open references/uninstall-and-cleanup.md]
  C --> D[Follow uninstall_and_cleanup workflow]

  B -->|install / upgrade / downgrade / migrate / device / compatibility| E{Existing BrainX packages or pinned version?}

  E -->|no| F[Resolve latest Python-compatible BrainX release via package index]
  F --> G[Confirm device extra and Target BrainX release]

  E -->|yes| H[Open references/compatibility-and-release-matching.md]
  H --> I[Select one BrainX release from compatibility matrix]

  G --> J[Inspect environments and prefer existing suitable venv]
  I --> J

  J --> K[Present complete specification with Target BrainX release]
  K --> L{User confirms?}
  L -->|yes| M[Execute install workflow]
  L -->|no| N[Revise specification or stop]

Loading

File-Level Changes

Change	Details	Files
Relocate the BrainX install skill from docs into the repository-level skills directory and adjust internal reference links.	Move SKILL.md from docs/skills/brainx-install to skills/brainx-install, preserving content structure while updating it Update markdown links to compatibility-and-release-matching.md to use the new references/ path under skills	docs/skills/brainx-install/SKILL.md skills/brainx-install/SKILL.md
Extend the BrainX skill to explicitly cover uninstall/cleanup flows and route those requests to a dedicated reference workflow.	Update the skill description to include uninstall, removal, and cleanup intents in the routing criteria Add a Request Routing section that directs uninstall/cleanup requests to references/uninstall-and-cleanup.md and keeps install/upgrade/downgrade on the main workflow Add a Reference Routing rule to open uninstall-and-cleanup.md for uninstall/cleanup and to use compatibility-and-release-matching.md only for environments with existing BrainX packages or pinned-version requests	skills/brainx-install/SKILL.md skills/brainx-install/references/uninstall-and-cleanup.md
Tighten installation rules around release selection, metadata usage, and environment choice for BrainX installs.	Require that for clean unpinned installs the agent resolve the exact latest Python-compatible BrainX release from read-only package index metadata and name it explicitly (vYYYY.M.D) Mandate opening the compatibility-and-release-matching reference for any existing-package or pinned-version workflow and treat each table row as an indivisible compatibility set Add a requirement to inventory the exact latest compatible BrainX release as part of environment inspection for clean installs Clarify that a suitable existing venv/Conda environment with Python >=3.11 should be reused when possible and that global or unrelated environments must not be modified	skills/brainx-install/SKILL.md skills/brainx-install/references/compatibility-and-release-matching.md
Refine the confirmation and reporting contract for BrainX installs to surface explicit target releases and package sets.	Extend the pre-mutation confirmation template to include the explicit target BrainX release in date-style form Require that for clean unpinned installs the device-specific meta-package and verified release be named explicitly in the expected final package set, rather than left to implicit pip resolution	skills/brainx-install/SKILL.md
Introduce a new uninstall-and-cleanup reference that defines a safe, environment-scoped BrainX removal workflow with optional JAX cleanup.	Define explicit BrainX and optional JAX package scopes, including normalization rules for distribution name variants Specify core rules for operating only on a confirmed non-global environment, routing all pip commands through the exact interpreter, and not removing shared dependencies or environments Define a multi-step uninstall workflow: inspect environment, inventory targets and reverse dependencies, explicit JAX cleanup choice, present a complete uninstall spec, execute confirmed pip uninstall commands, verify via metadata and pip check, and report results Provide structured templates for the uninstall specification and final report, including handling of reverse dependencies and failure cases	skills/brainx-install/references/uninstall-and-cleanup.md
Tighten compatibility matrix semantics for older BrainX releases by constraining the acceptable BrainX version ranges.	Adjust the BrainX version range column for several historical releases to add upper bounds (<=) on supported BrainX versions, clarifying compatibility Document that the compatibility matrix is specifically for the second release-selection case (existing packages or pinned version), to be read before release selection and treated as indivisible rows	skills/brainx-install/references/compatibility-and-release-matching.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• In the 'Select One Release' section, the sentence starting with 'First case, When no BrainX...' is awkwardly capitalized and punctuated; consider simplifying to two sentences (e.g., 'In the first case, when no BrainX...' without the comma) to improve clarity.
• The final note in 'Reference Routing' still instructs to 'use the unpinned quick-install path' for clean installs, but earlier sections now require resolving the exact latest release from package-index metadata; aligning this wording with the updated latest-release resolution behavior would avoid conflicting guidance.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In the 'Select One Release' section, the sentence starting with 'First case, When no BrainX...' is awkwardly capitalized and punctuated; consider simplifying to two sentences (e.g., 'In the first case, when no BrainX...' without the comma) to improve clarity.
- The final note in 'Reference Routing' still instructs to 'use the unpinned quick-install path' for clean installs, but earlier sections now require resolving the exact latest release from package-index metadata; aligning this wording with the updated latest-release resolution behavior would avoid conflicting guidance.

## Individual Comments

### Comment 1
<location path="skills/brainx-install/SKILL.md" line_range="80" />
<code_context>
 ## 3. Select One Release

-When no BrainX meta-package or ecosystem component is installed and the user has not requested a specific version, do not open the compatibility reference. Prefer the unpinned official quick-install form that matches the confirmed device target: `BrainX`, `BrainX[cpu]`, `BrainX[cuda12]`, `BrainX[cuda13]`, or `BrainX[tpu]`.
+First case, When no BrainX meta-package or ecosystem component is installed and the user has not requested a specific version, do not open the compatibility reference. Use read-only official package-index metadata with the proposed interpreter to identify the exact latest Python-compatible BrainX release, then report it in the form `latest (vYYYY.M.D)`. For example, report `latest (v2026.7.9)` when `2026.7.9` is the verified current release. 

-When BrainX packages are already installed or the user requests a specific pinned version, follow **Reference Routing** at the end of this skill, then apply the matching procedure below.
</code_context>
<issue_to_address>
**nitpick (typo):** Fix capitalization in "First case, When no" for grammatical correctness.

"First case, When no BrainX meta-package..." is grammatically off due to the capitalized "When" after a comma. Please rephrase, e.g. "First case: when no BrainX meta-package..." or "First, when no BrainX meta-package..." to improve flow and capitalization.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

nitpick (typo): Fix capitalization in "First case, When no" for grammatical correctness.

"First case, When no BrainX meta-package..." is grammatically off due to the capitalized "When" after a comma. Please rephrase, e.g. "First case: when no BrainX meta-package..." or "First, when no BrainX meta-package..." to improve flow and capitalization.