mainsequence 4.4.32__tar.gz → 5.0.2__tar.gz

{mainsequence-4.4.32/mainsequence.egg-info → mainsequence-5.0.2}/PKG-INFO

@@ -1,56 +1,16 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 4.4.32
+Version: 5.0.2
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
-License: MainSequence GmbH SDK License Agreement
-        This License Agreement (the "License") governs the use, modification, and distribution of the software provided by MainSequence GmbH (the "Licensor"). The software (the "Software") is provided to you under the terms of this License. By using the Software, you agree to the terms of this License.
-        
-        TERMS AND CONDITIONS
-        0. Definitions
-        "Personal Use": Use by an individual for personal purposes that are not connected to any business, organization, or commercial activity.
-        "Internal Use": Use within a business, organization, or other entity, provided it is not made accessible to third parties or used for commercial purposes.
-        "Commercial Use": Use of the Software in exchange for monetary or other compensation, including hosting, offering Software as a service, selling the Software, or using it in a product or service for sale.
-        "License Agreement": The legally binding agreement between the Licensor and the licensee (you), subject to the terms outlined in this License.
-        1. Grant of License
-        1.1 Personal and Internal Use
-        The Licensor grants you a limited, non-exclusive, non-transferable, revocable license to use and modify the Software for personal or internal use only, provided that such use is strictly subject to this License Agreement and continues only while the License Agreement remains in effect.
-        Upon termination of this License Agreement, all rights to use the Software for personal or internal purposes shall be immediately revoked, and you must cease all use of the Software.
-        1.2 Modification
-        You are permitted to modify the Software solely for your own personal or internal use, subject to the restrictions outlined in this License Agreement.
-        You are not permitted to distribute, sublicense, or otherwise transfer modified or unmodified versions of the Software to any third party.
-        1.3 Prohibited Redistribution
-        You may not redistribute, sublicense, sell, lease, rent, or otherwise transfer the Software, whether in its original form or as modified by you, to any third party.
-        Any attempt to distribute or transfer the Software in any way, without explicit permission from MainSequence GmbH, is strictly prohibited.
-        2. Prohibition of Commercial Use
-        The Software may not be used for any commercial purposes without obtaining a separate commercial license from MainSequence GmbH.
-        Examples of prohibited commercial use include, but are not limited to:
-        Hosting or offering the Software as a service to others, either modified or unmodified.
-        Using the Software as part of a commercial product or service provided to customers for a fee.
-        Using the Software in any production environment that generates income, directly or indirectly, from its use.
-        3. Termination
-        This License Agreement will automatically terminate if you fail to comply with any of its terms.
-        Upon termination of this License, you must immediately cease all use of the Software, destroy all copies (modified or unmodified), and remove the Software from any devices or systems on which it is installed.
-        MainSequence GmbH reserves the right to terminate this License at its discretion for any violation of its terms or for any other reason.
-        4. Commercial License
-        If you wish to use the Software for commercial purposes, you must contact MainSequence GmbH to negotiate and obtain a separate commercial license. The terms of the commercial license, including any fees, will be negotiated separately from this License Agreement.
-        Without a valid commercial license, you are strictly prohibited from using the Software for any commercial activity.
-        5. Disclaimer of Warranty
-        THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL MAINSEQUENCE GMBH OR THE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-        
-        6. Limitation of Liability
-        IN NO EVENT SHALL MAINSEQUENCE GMBH BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
-        
-        7. Governing Law
-        This License Agreement shall be governed by and construed in accordance with the laws of the jurisdiction where MainSequence GmbH is located, without regard to its conflict of law provisions.
+License-Expression: LicenseRef-MainSequence-Proprietary
 Project-URL: Homepage, https://github.com/mainsequence-sdk/mainsequence-sdk
 Project-URL: Issues, https://github.com/mainsequence-sdk/mainsequence-sdk/issues
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
-Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.11
+Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: alembic>=1.18.4
@@ -61,14 +21,15 @@ Requires-Dist: numpy
 Requires-Dist: opentelemetry-api
 Requires-Dist: opentelemetry-exporter-otlp
 Requires-Dist: opentelemetry-sdk
+Requires-Dist: packaging>=24.2
 Requires-Dist: pandas
 Requires-Dist: psutil
 Requires-Dist: psycopg2>=2.9.12
-Requires-Dist: pydantic
-Requires-Dist: pytz
+Requires-Dist: pydantic<3,>=2.11
 Requires-Dist: pyyaml
 Requires-Dist: requests
 Requires-Dist: sqlalchemy<3,>=2
+Requires-Dist: starlette
 Requires-Dist: structlog
 Requires-Dist: tqdm
 Requires-Dist: typer
@@ -270,7 +231,7 @@ If you need the exact SDK surface:
 ## Package metadata
 
 - Package name: `mainsequence`
-- Python: `>=3.11`
+- Python: `>=3.13`
 - CLI entry point: `mainsequence`
 
 Project metadata is defined in [pyproject.toml](pyproject.toml).

{mainsequence-4.4.32 → mainsequence-5.0.2}/README.md

@@ -188,7 +188,7 @@ If you need the exact SDK surface:
 ## Package metadata
 
 - Package name: `mainsequence`
-- Python: `>=3.11`
+- Python: `>=3.13`
 - CLI entry point: `mainsequence`
 
 Project metadata is defined in [pyproject.toml](pyproject.toml).

{mainsequence-4.4.32 → mainsequence-5.0.2}/agent_scaffold/AGENTS.md

@@ -23,29 +23,41 @@ installed SDK version with the managed skills pin:
 - `mainsequence project update-sdk --path .`
 
 After the SDK update, inspect `.agents/skills/mainsequence/PINNED_FROM.txt`.
-Its `pinned_version=...` value records the SDK version that supplied the copied
-Main Sequence skills. Compare that value with the installed SDK version reported
-by `mainsequence --version`.
+The schema-2 record describes both sources installed by
+`mainsequence project update_agent_skills`:
+
+- `sdk_version=...` and `sdk_skills_path=...` identify the SDK-owned execution
+  skills copied from the target project's installed SDK;
+- `platform_manifest_version=...`, `platform_manifest_sha256=...`,
+  `platform_ontology_sha256=...`, and the
+  `platform_resource.<name>.*` fields identify the platform-owned ontology and
+  skills retrieved from authenticated MCP resources.
+
+`pinned_version=...` remains as a backward-readable alias of `sdk_version`.
+Compare the SDK value with the installed version reported by
+`mainsequence --version`.
 
 Refresh the managed scaffold only when `PINNED_FROM.txt` is missing or its
 `pinned_version` differs from the installed SDK version:
 
-- `mainsequence project update AGENTS.md --path .`
 - `mainsequence project update_agent_skills --path .`
+- `mainsequence project update AGENTS.md --path .`
 
-If `pinned_version` already matches the installed SDK version, do not refresh
-`AGENTS.md` or `.agents/skills/mainsequence/` as a startup ritual; continue with
-the task.
+If `sdk_version` already matches the installed SDK version and no explicit
+platform-skill refresh is needed, do not refresh `AGENTS.md` or
+`.agents/skills/mainsequence/` as a startup ritual; continue with the task.
 
 Canonical Main Sequence documentation root:
 `https://mainsequence-sdk.github.io/mainsequence-sdk/`
 
 ## Agent Job
 
-You are the intelligence project builder for a Main Sequence repository.
+You are the SDK execution orchestrator for a Main Sequence repository.
 
-Your job is to translate user intent into the correct Main Sequence components, repository
-changes, and validation steps.
+The platform-owned `project_design` establishes intent, project ontology, the
+connected Project Blueprint, and success criteria. Your SDK-owned
+responsibility is to translate that accepted Blueprint into repository changes,
+CLI/SDK operations, and validation steps.
 
 Core responsibilities:
 
@@ -64,8 +76,7 @@ Core responsibilities:
 - translate user business logic into reusable code under `src/` so it can be reused by APIs,
   dashboards, jobs, and other project components instead of duplicating logic in integration
   layers
-- maintain the repository through explicit `.agents/` project-state files and the bug auditor skill
-  for blocker and SDK/platform issue assessment
+- use the bug auditor skill for blocker and SDK/platform issue assessment
 
 Typical outcomes include:
 
@@ -77,7 +88,7 @@ Typical outcomes include:
   Center surface before building or deploying it
 - build reusable business logic in `src/` and keep thin integration layers in APIs, jobs, and
   dashboards
-- keep the repository auditable through project-state records, blocker tracking, and bug reporting
+- assess blockers and suspected SDK or platform issues from concrete repository and runtime evidence
 
 Working rules for this role:
 
@@ -105,13 +116,6 @@ User-resolution rule for agents:
 
 Delegation rules:
 
-- when work is delegated or queued for later, write the task in `.agents/tasks.md` according to
-  the skill that should execute it
-- each delegated or queued task in `.agents/tasks.md` must state:
-  - the exact task scope
-  - the owning skill
-  - the expected output, decision, or artifact
-  - the validation or evidence required before it can be marked complete
 - if delegation is available, declare for each sub-agent:
   - the exact task it owns
   - the exact skill or skills it must use
@@ -173,10 +177,17 @@ Use the latest relevant documentation or specialized skill for the task at hand.
 
 Typical routing:
 
-- project setup, local checkout, and CLI environment:
-  `.agents/skills/mainsequence/project_builder/SKILL.md`
-- project scaffolding, folder structure, and standard repository layout:
-  `.agents/skills/mainsequence/project_builder/SKILL.md`
+- project architecture, ontology, and Project Blueprint:
+  `.agents/skills/mainsequence/project_design/SKILL.md`
+- project setup, local checkout, CLI environment, scaffolding, and standard
+  repository layout:
+  `.agents/skills/mainsequence/sdk_project_execution/SKILL.md`
+- local environment repair, project authentication refresh, SDK updates,
+  managed skill refresh, and canonical project sync:
+  `.agents/skills/mainsequence/maintenance/project-maintenance/SKILL.md`
+- turning an existing project into a project-backed coding agent, defining
+  project-owned skills, and authoring `.agents/agent_card.json`:
+  `.agents/skills/mainsequence/project_to_agent/SKILL.md`
 - project status audits, blocker analysis, failure classification, and upstream SDK assessment:
   `.agents/skills/mainsequence/maintenance/bug_auditor/SKILL.md`
 - DataNodes, updates, identifiers, schema, metadata:
@@ -218,27 +229,28 @@ For any non-trivial Main Sequence task:
 
 1. Read the latest relevant Main Sequence documentation.
 2. Compare the implementation against the latest documented behavior.
-
-4. Check `.agents/tasks.md` for current priorities.
-
-7. Confirm you are in the correct project checkout, or use `--path` explicitly.
-8. Confirm platform context with:
+3. Confirm you are in the correct project checkout, or use `--path` explicitly.
+4. Confirm platform context with:
    `mainsequence project current --debug`
-9. Before validations or live checks, run:
+5. Before validations or live checks, run:
    `mainsequence project refresh_token --path .`
-10. If git push or pull is required, use:
+6. If git push or pull is required, use:
     `mainsequence project open-signed-terminal <PROJECT_ID>`
-11. Before proceeding with non-trivial Main Sequence work, update the project SDK:
+7. Before proceeding with non-trivial Main Sequence work, update the project SDK:
     `mainsequence project update-sdk --path .`
-12. After updating the SDK, compare `mainsequence --version` with
-    `.agents/skills/mainsequence/PINNED_FROM.txt` field `pinned_version=...`.
-13. If `PINNED_FROM.txt` is missing or `pinned_version` differs from the installed
-    SDK version, refresh the managed scaffold files:
-    `mainsequence project update AGENTS.md --path .`
+8. After updating the SDK, compare `mainsequence --version` with
+    `.agents/skills/mainsequence/PINNED_FROM.txt` field `sdk_version=...`
+    (`pinned_version=...` is its compatibility alias), and verify that the
+    sentinel contains platform manifest and resource hashes.
+9. If `PINNED_FROM.txt` is missing, `sdk_version` differs from the installed
+    SDK version, or a platform-skill refresh is explicitly required, refresh
+    the managed scaffold files:
     `mainsequence project update_agent_skills --path .`
-14. If `pinned_version` already matches the installed SDK version, do not refresh
-    `AGENTS.md` or `.agents/skills/mainsequence/` as a startup ritual.
-15. Verify platform state with the CLI or platform tooling instead of guessing.
+    `mainsequence project update AGENTS.md --path .`
+10. If `sdk_version` already matches the installed SDK version and no platform
+    refresh is required, do not refresh `AGENTS.md` or
+    `.agents/skills/mainsequence/` as a startup ritual.
+11. Verify platform state with the CLI or platform tooling instead of guessing.
 
 ## Orchestrator Rule
 
@@ -246,16 +258,23 @@ Use the skills as an orchestrated sequence, not as isolated documents.
 
 Default pattern:
 
-1. `.agents/skills/mainsequence/project_builder/SKILL.md`
-2. the relevant domain skill
-
-Before the final response:
+1. `.agents/skills/mainsequence/project_design/SKILL.md`
+2. `.agents/skills/mainsequence/sdk_project_execution/SKILL.md`
+3. the relevant domain skill
 
-- update the relevant `.agents/` project-state files whenever project understanding, verified
-  state, open tasks, blockers, or historical record changed during the turn
+When the intended project surface is a project-backed coding agent, apply
+`.agents/skills/mainsequence/project_to_agent/SKILL.md` after the relevant
+project behavior exists and has been verified. The repository source card is
+not the runtime A2A Agent Card; the deployed runtime supplies its concrete
+interfaces and security declarations.
 
-Always use `.agents/skills/mainsequence/project_builder/SKILL.md` as the source of truth for project
-scaffolding, folder structure, and standard repository layout.
+Use `.agents/skills/mainsequence/project_design/SKILL.md` as the platform
+source of truth for intent and ontology. Use
+`.agents/skills/mainsequence/sdk_project_execution/SKILL.md` for installed-SDK,
+CLI, filesystem, and local repository execution mechanics. Use
+`.agents/skills/mainsequence/maintenance/project-maintenance/SKILL.md` for
+repeatable environment, authentication, SDK, scaffold-refresh, and project-sync
+routines.
 
 ## Core Working Rules
 
@@ -266,8 +285,8 @@ scaffolding, folder structure, and standard repository layout.
 - do not hide failures
 - record the exact failing step, command, or workflow
 - when hitting a roadblock, blocker, or error, report it back to the user clearly and promptly
-- if local code or local docs conflict with the latest Main Sequence docs, record the discrepancy
-  and create follow-up work
+- if local code or local docs conflict with the latest Main Sequence docs, report the discrepancy
+  and the concrete next action
 - when unsure, verify
 - if the active virtual environment is missing libraries that are already declared in
   `requirements.txt`, install those missing libraries into the virtual environment before
@@ -330,7 +349,7 @@ Rules:
 
 If something may be a Main Sequence SDK, documentation, or platform issue:
 
-- record what failed
+- report what failed
 - explain why it may be a Main Sequence issue
 - suggest a concrete improvement
 
@@ -341,10 +360,4 @@ If something may be a Main Sequence SDK, documentation, or platform issue:
 - prefer explicit facts over vague statements
 - surface failures early
 - distinguish verified facts from assumptions
-
-## Project-State Files Under `.agents/`
-
-
-Do not improvise their meaning in domain skills. Use the project bootstrap skill rules to reconcile
-them after material work.
 <!-- mainsequence-agent-scaffold:end -->

{mainsequence-4.4.32/agent_scaffold/skills/a2a_communication → mainsequence-5.0.2/agent_scaffold/skills/a2a_sdk_execution}/SKILL.md

@@ -1,12 +1,15 @@
 ---
-name: a2a_communication
-description: Canonical guidance for discovering agents and sending session-scoped A2A requests through Main Sequence.
+name: mainsequence-a2a-sdk-execution
+description: Execute the platform A2A communication flow with the installed Main Sequence CLI or Python SDK after the platform-owned A2A skill has established the language-neutral protocol semantics.
 ---
 
-# A2A Communication
+# Main Sequence A2A SDK Execution
 
-Use this skill when you need to discover another agent, create or resolve a
-target `AgentSession`, and send a bounded A2A request.
+Use this SDK-owned execution skill after reading the platform-owned
+`a2a_communication` skill. It provides concrete CLI and Python mechanics for
+discovering another agent, creating or resolving a target `AgentSession`, and
+sending a bounded A2A request. It is not the canonical platform protocol
+definition.
 
 ## Canonical CLI Path
 

{mainsequence-4.4.32 → mainsequence-5.0.2}/agent_scaffold/skills/data_access/exploration/SKILL.md

@@ -44,7 +44,7 @@ This skill discovers and identifies data. It does not publish, redesign, or defi
 ## Route Adjacent Work
 
 - project bootstrap, scaffolding, and routing:
-  `.agents/skills/mainsequence/project_builder/SKILL.md`
+  `.agents/skills/mainsequence/project_design/SKILL.md`
 - `DataNode` creation or modification:
   `.agents/skills/mainsequence/data_publishing/data_nodes/SKILL.md`
 - `MetaTable` registration or operation work:

{mainsequence-4.4.32 → mainsequence-5.0.2}/agent_scaffold/skills/maintenance/bug_auditor/SKILL.md

@@ -20,8 +20,7 @@ This skill is for diagnosis and assessment. Default behavior is read-only unless
 ## This Skill Can Do
 
 - inspect project state and summarize completion status
-- read `.agents/tasks.md` and `.agents/status.md` first when they exist
-- use repo state, logs, test output, stderr, and task files as evidence
+- use repo state, logs, test output, and stderr as evidence
 - classify failures into:
   - target-project issue
   - environment or credentials issue
@@ -49,7 +48,7 @@ This skill audits. It does not implement by default.
 ## Route Adjacent Work
 
 - bootstrap, routing, and repo structure:
-  `.agents/skills/mainsequence/project_builder/SKILL.md`
+  `.agents/skills/mainsequence/project_design/SKILL.md`
 - DataNode implementation issues:
   `.agents/skills/mainsequence/data_publishing/data_nodes/SKILL.md`
 - MetaTable implementation issues:
@@ -62,18 +61,17 @@ This skill audits. It does not implement by default.
   `.agents/skills/mainsequence/platform_operations/access_control_and_sharing/SKILL.md`
 - Streamlit dashboard deployment or release issues:
   `.agents/skills/mainsequence/platform_operations/orchestration_and_releases/SKILL.md`
+- environment repair, authentication refresh, SDK updates, managed skill
+  refresh, and project sync after the failure is classified:
+  `.agents/skills/mainsequence/maintenance/project-maintenance/SKILL.md`
 
 Streamlit dashboard design and implementation failures are target-project application code issues unless the evidence points to Main Sequence deployment, resource discovery, image selection, release creation, or platform runtime behavior.
 
 ## Read First
 
 1. `AGENTS.md`
-2. `.agents/skills/mainsequence/project_builder/SKILL.md`
-3. `.agents/tasks.md` when it exists
-4. `.agents/status.md` when it exists
-5. `.agents/record.md` when stable references or project ids matter
-6. `.agents/journal.md` when repeated failures or prior investigations may be relevant
-7. the latest relevant Main Sequence docs for the failing workflow
+2. `.agents/skills/mainsequence/project_design/SKILL.md`
+3. the latest relevant Main Sequence docs for the failing workflow
 
 ## Inputs This Skill Needs
 
@@ -101,17 +99,15 @@ For every audit, decide:
 
 ### 1. Stay read-only unless edits were explicitly requested
 
-Do not modify code, docs, or project-state files unless the task explicitly asks for edits.
+Do not modify code or docs unless the task explicitly asks for edits.
 
-### 2. Start with project-state files
+### 2. Start with current evidence
 
-Read `.agents/tasks.md` and `.agents/status.md` first when they exist.
-
-Use them as hypotheses, not as proof.
+Inspect the repository state, available logs, failing commands, stderr, and test output.
 
 ### 3. Use evidence, not impressions
 
-Use repo state, logs, test output, stderr, and task files as evidence.
+Use repo state, logs, test output, and stderr as evidence.
 
 When reporting a blocker or failure, include:
 
@@ -127,7 +123,6 @@ Before each major investigation step, emit a short progress update that says wha
 
 Especially announce when you are:
 
-- reading `.agents/tasks.md` or `.agents/status.md`
 - inspecting a failing command, traceback, or stderr excerpt
 - checking the local `mainsequence` package or version
 - inspecting or cloning the public `mainsequence-sdk` repository
@@ -184,7 +179,6 @@ When reviewing an audit, look for:
 
 Do not claim audit completion until you have checked:
 
-- `.agents/tasks.md` and `.agents/status.md` first when they exist
 - the overall state is one of:
   - `finished`
   - `in_progress`

mainsequence-5.0.2/agent_scaffold/skills/maintenance/project-maintenance/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: project-maintenance
+description: Maintain an existing Main Sequence project checkout using the SDK-version-matched CLI. Use for inspecting project state, building or repairing .venv, refreshing local project authentication, updating the SDK, refreshing SDK and platform skills plus AGENTS.md, publishing changes with project sync, or diagnosing a partially completed maintenance workflow.
+---
+
+# Main Sequence Project Maintenance
+
+Maintain the local project through the installed Main Sequence CLI. Treat the
+CLI as the canonical implementation of SDK-version-specific filesystem, `uv`,
+authentication, scaffold, and Git behavior. Select and sequence commands here;
+do not reproduce their Python implementation or replace them with ad hoc shell
+workflows.
+
+## Preserve The Boundary
+
+Own:
+
+- local project inspection and maintenance sequencing;
+- `.venv`, SDK, managed skill, `AGENTS.md`, and Git-release workflows;
+- precondition checks, explicit approval gates, and partial-failure diagnosis.
+
+Do not own:
+
+- platform ontology or Project Blueprint design;
+- domain implementation for MetaTables, DataNodes, APIs, jobs, or releases;
+- backend repository reconciliation;
+- MCP authentication or access-token extraction;
+- project-owned skills outside `.agents/skills/mainsequence/`.
+
+Route architecture changes to `project_design`, implementation routing to
+`sdk_project_execution`, and failure classification to
+`maintenance/bug_auditor` when diagnosis extends beyond the maintenance
+workflow itself.
+
+## Inspect Before Changing State
+
+1. Read `AGENTS.md` and the relevant repository skills.
+2. Confirm the repository root and the user's requested maintenance outcome.
+3. Inspect project and Git state:
+
+   ```bash
+   mainsequence project current --debug --json
+   mainsequence project sdk-status --path . --json
+   git status --short
+   ```
+
+4. Separate existing user changes from changes created by the maintenance
+   task. Never assume every uncommitted file belongs to the current task.
+5. Read command help when the installed SDK differs from the instructions in
+   this skill. The installed CLI is authoritative for its version.
+
+If `mainsequence` is unavailable, stop and report that the SDK CLI must be
+installed or provided by the local development integration. Do not use an MCP
+bearer token or an unpinned downloaded CLI as a substitute.
+
+## Build Or Repair The Local Environment
+
+Build the project environment with:
+
+```bash
+mainsequence project build_local_venv --path .
+```
+
+The command reads the project Python requirement, resolves `uv`, creates
+`.venv`, and synchronizes dependencies. Do not manually parse
+`pyproject.toml` or reconstruct those steps.
+
+When an existing `.venv` is incompatible, show the detected mismatch and ask
+before replacing it. Only then run:
+
+```bash
+mainsequence project build_local_venv --path . --recreate
+```
+
+Treat `.venv` as generated state, never as source code or durable project
+documentation.
+
+## Refresh Project Authentication
+
+Refresh only the CLI-managed runtime authentication entries in the project
+`.env`:
+
+```bash
+mainsequence project refresh_token --path .
+```
+
+Require normal Main Sequence CLI login first. Never print, inspect, summarize,
+copy, or return access and refresh token values. Do not attempt to extract the
+calling MCP host's protected bearer token. If authentication is unavailable,
+stop and request login through the normal CLI or development integration.
+
+## Update The Project SDK
+
+Inspect the current status, preview the update, and then update when requested
+or required by repository instructions:
+
+```bash
+mainsequence project sdk-status --path . --json
+mainsequence project update-sdk --path . --dry-run
+mainsequence project update-sdk --path .
+```
+
+`update-sdk` updates the lock and local environment. It does not publish the
+working tree. After the SDK changes, refresh the managed agent context and run
+the repository-specific validation required by `AGENTS.md`.
+
+Do not automatically commit or push an SDK update unless the user also asked
+to publish the project changes.
+
+## Refresh Managed Skills And Instructions
+
+Refresh the SDK-owned and platform-owned skills first, then update the managed
+Main Sequence block in `AGENTS.md`:
+
+```bash
+mainsequence project update_agent_skills --path .
+mainsequence project update AGENTS.md --path .
+```
+
+Verify `.agents/skills/mainsequence/PINNED_FROM.txt` after success:
+
+- `sdk_version` must match the installed project SDK;
+- platform manifest, ontology, and resource hashes must be present;
+- project-owned skills outside `.agents/skills/mainsequence/` must remain
+  untouched.
+
+The skill update is staged and atomic. If it fails, report the failing lane and
+preserve the previous valid managed tree. Because this operation can update
+this skill, reload the refreshed `project-maintenance/SKILL.md` before starting
+another maintenance routine.
+
+## Publish With Canonical Project Sync
+
+Use project sync only when the user intends to commit, tag, and push all
+reviewed project changes.
+
+Before execution:
+
+```bash
+git status --short
+git diff --stat
+mainsequence project sync --path . -m "<specific commit message>" --dry-run
+```
+
+Review every pending file because the command stages with `git add -A`. Do not
+continue when unrelated or unexplained changes would be included.
+
+After review:
+
+```bash
+mainsequence project sync --path . -m "<specific commit message>"
+```
+
+The canonical command always:
+
+1. applies a patch version bump;
+2. runs `uv lock`;
+3. runs `uv sync`;
+4. exports locked production requirements;
+5. stages and commits the changes;
+6. creates an annotated `v<version>` tag; and
+7. pushes the branch and tag with `--follow-tags`.
+
+Do not offer alternate bump modes, a no-push mode, or a hand-written sequence
+of equivalent commands. Do not call `sync-after-commit` or any backend repair
+endpoint. The GitHub branch-push webhook owns backend repository
+reconciliation.
+
+## Diagnose Partial Completion Before Retrying
+
+Never rerun an entire mutating workflow blindly.
+
+- After an environment failure, inspect `.venv`, the declared Python
+  requirement, and the exact failing `uv` output.
+- After an SDK update failure, inspect `pyproject.toml`, `uv.lock`, the active
+  environment, and the failed command before retrying.
+- After a skill refresh failure, keep the previous managed tree and identify
+  whether the SDK or platform lane failed.
+- After a sync failure, inspect `git status`, `git log -1`, the current project
+  version, tags pointing at `HEAD`, the upstream branch, and remote tags before
+  deciding which step remains.
+
+A blind sync retry may create another patch bump or collide with an existing
+commit or tag.
+
+## Validate And Report
+
+Run only repository-relevant validation discovered from `AGENTS.md`, project
+documentation, and the changed files. Report:
+
+- the maintenance routine performed;
+- the project path and installed SDK version;
+- files or generated state changed;
+- validation run and its result;
+- whether changes remain local or were committed, tagged, and pushed;
+- any remaining authentication, environment, Git, or webhook verification
+  gap.
+
+Never claim backend reconciliation succeeded solely because the local push
+succeeded. Verify backend state separately when the task requires that claim.