coreslopper 0.0.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coreslopper",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "description": "An open-source, Claude Code-native workflow for producing music videos from brief to render.",

package/runtime/.github/workflows/ci.yml

@@ -14,14 +14,14 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: 22
           cache: npm
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
 
@@ -29,7 +29,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y ffmpeg
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v10.3.3
 
       - name: Install Node dependencies
         run: npm ci
@@ -56,7 +56,7 @@ jobs:
         run: npm run cli -- contact-sheet projects/demo
 
       - name: Cache Remotion browser
-        uses: actions/cache@v4
+        uses: actions/cache@v6
         with:
           path: ~/.cache/remotion
           key: remotion-browser-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
@@ -79,10 +79,12 @@ jobs:
           TARBALL=$(ls "$RUNNER_TEMP"/pkg/coreslopper-*.tgz)
           npx -y -p "$TARBALL" coreslopper init "$RUNNER_TEMP/coreslopper-npx" --yes --no-install --no-git --skip-project
           npx -y -p "$TARBALL" coreslopper doctor "$RUNNER_TEMP/coreslopper-npx"
+          npx -y -p "$TARBALL" coreslopper update "$RUNNER_TEMP/coreslopper-npx" --no-install | tee "$RUNNER_TEMP/update.log"
+          grep -q "already up to date" "$RUNNER_TEMP/update.log"
           test -f "$RUNNER_TEMP/coreslopper-npx/packages/cli/src/init.ts"
 
       - name: Upload demo artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: demo-artifacts
           path: |

package/runtime/.github/workflows/release.yml

@@ -0,0 +1,78 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v5
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish:
+    needs: release-please
+    # Publish when release-please just cut a release, or on a manual retry
+    # (workflow_dispatch publishes the version currently in package.json).
+    if: needs.release-please.outputs.release_created == 'true' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      id-token: write # npm trusted publishing (OIDC) and provenance
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name || github.ref }}
+
+      # Node 24 ships npm 11, which supports npm trusted publishing.
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+          cache: npm
+
+      - name: Install ffmpeg
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Tests
+        run: npm test
+
+      - name: Build and smoke-test package
+        run: |
+          mkdir -p "$RUNNER_TEMP/pkg"
+          npm pack --pack-destination "$RUNNER_TEMP/pkg"
+          TARBALL=$(ls "$RUNNER_TEMP"/pkg/coreslopper-*.tgz)
+          npx -y -p "$TARBALL" coreslopper init "$RUNNER_TEMP/coreslopper-npx" --yes --no-install --no-git --skip-project
+          npx -y -p "$TARBALL" coreslopper doctor "$RUNNER_TEMP/coreslopper-npx"
+
+      # Trusted publishing: the npm CLI detects the OIDC environment and exchanges
+      # it for a short-lived publish token. No npm token in the repository, no OTP.
+      # Provenance is generated automatically for a public package from a public repo.
+      # The tarball was already built and tested above, so lifecycle scripts are skipped.
+      - name: Publish to npm
+        run: npm publish --access public --ignore-scripts

package/runtime/.release-please-manifest.json

@@ -0,0 +1 @@
+{".":"0.2.0"}

package/runtime/AGENTS.md

@@ -131,6 +131,7 @@ npm run schema
 | `npm run cli -- validate-file <file>` | Validate one changed artifact (used by the hook). |
 | `npm run cli -- doctor` | Check workspace, tools, fonts, Remotion, and keys. |
 | `npx coreslopper init [dir]` | Create a workspace, install tools, configure fal.ai, Higgsfield, and Suno. |
+| `npx coreslopper@latest update [dir]` | Update a workspace to the latest workflow; keeps local edits (`--dry-run`, `--force`). |
 | `npx coreslopper doctor` | Check a workspace from outside it. |
 | `npx coreslopper new <slug> --budget <usd>` | Create a project inside a workspace. |
 | `npm run build` | Build `runtime/` and the npx bundle in `dist/`. |
@@ -140,7 +141,7 @@ In Claude Code: `/new-video`, `/video-next`, `/video-status`.
 
 ## Distribution
 
-The root package is published as `coreslopper`. `npm run build` copies the tracked workflow into `runtime/` and bundles `packages/cli/src/npx.ts` into `dist/cli.js`; `prepack` runs the same build. The npm package ships the onboarding CLI (init, doctor, new, status, validate) plus the runtime snapshot, not the Remotion dependency tree. `npx coreslopper init` copies `runtime/` into a private workspace, then the workspace's own `npm install` provides rendering and audio-analysis dependencies. Never publish generated media or `.env`.
+The root package is published as `coreslopper`. `npm run build` copies the tracked workflow into `runtime/` and bundles `packages/cli/src/npx.ts` into `dist/cli.js`; `prepack` runs the same build. The npm package ships the onboarding CLI (init, update, doctor, new, status, validate) plus the runtime snapshot, not the Remotion dependency tree. `npx coreslopper init` copies `runtime/` into a private workspace, then the workspace's own `npm install` provides rendering and audio-analysis dependencies. Never publish generated media or `.env`.
 
 ## Skills
 

package/runtime/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## [0.2.0](https://github.com/hemi1986/coreslopper/compare/v0.1.0...v0.2.0) (2026-11-08)
+
+
+### Features
+
+* add `coreslopper update` to merge a newer workflow into a workspace ([3eddb5c](https://github.com/hemi1986/coreslopper/commit/3eddb5caa64a534a9bf21ca13d45d24c747976e3))
+* add `coreslopper update` to merge a newer workflow into a workspace ([1d10ffd](https://github.com/hemi1986/coreslopper/commit/1d10ffda2a6639d1a5b2a489564a54c9b2422cda))
+
+## 0.1.0 (2026-11-08)
+
+
+### Features
+
+* add example brand kit and brand schema ([08ea9d5](https://github.com/hemi1986/coreslopper/commit/08ea9d579fd48e6ff4a4f13e85d4437b3d3b33f5))
+* add Higgsfield provider and setup quickstarts ([6ced780](https://github.com/hemi1986/coreslopper/commit/6ced780ce9effddfb0272e11eff51939610da2f9))
+* add lip-sync clips for storyboard shots ([3403cf6](https://github.com/hemi1986/coreslopper/commit/3403cf6efde67025dafc7ecdee583c31668027ad))
+* add lip-sync shots and lyrics-first alignment ([d6534a9](https://github.com/hemi1986/coreslopper/commit/d6534a954bf6088f01732a525f629da4426a95d9))
+* add npx onboarding and workspace bootstrap ([2393370](https://github.com/hemi1986/coreslopper/commit/2393370392eacb25d9045fb5b700281a4e88b062))
+* add timing hooks, media helpers, stage reset, and MCP docs ([0b9ef19](https://github.com/hemi1986/coreslopper/commit/0b9ef1917aced6a0647f3dc8baa07222997e2f1a))
+* initial coreslopper workflow and motion-only demo ([a088d10](https://github.com/hemi1986/coreslopper/commit/a088d10e63f3312ef94f8acaa29eb8acc4dfeed4))
+* local ffmpeg bootstrap and media command polish ([ab347af](https://github.com/hemi1986/coreslopper/commit/ab347af580ecd4357bc0e4df8390b3d34735bb1c))
+
+
+### Bug Fixes
+
+* **audio-analysis:** align lyrics first and keep Unicode text ([ac35d0d](https://github.com/hemi1986/coreslopper/commit/ac35d0d33336e61a9bcc68c515f3a85088a8198f))
+* keep character reference media out of git ([bb253f0](https://github.com/hemi1986/coreslopper/commit/bb253f091e7bcc7e761dce64ea90e6aaf6bed367))
+
+
+### Documentation
+
+* mark workflow as work in progress ([cd5c1e8](https://github.com/hemi1986/coreslopper/commit/cd5c1e8275ebec06f772eb59a313bf3fc7b97b32))

package/runtime/CONTRIBUTING.md

@@ -82,7 +82,7 @@ The `publish` job uses npm trusted publishing (OIDC): no npm token in the reposi
 
 ### First time only: placeholder and trusted publisher
 
-A trusted publisher can only be configured for a package that already exists on npm. Publish a placeholder once by hand (this is the only step that needs 2FA):
+A trusted publisher can only be configured for a package that already exists on npm. Publish once by hand (this is the only step that needs 2FA; pass `--otp=<code>` when the shell cannot open a browser):
 
 ```bash
 npm login
@@ -91,6 +91,8 @@ npm publish --access public
 npm version 0.1.0 --no-git-tag-version   # back to the version release-please expects
 ```
 
+With staged publishing, npm answers the first publish with a stub `0.0.0-stage` placeholder and holds `0.0.0` for approval on npmjs.com. The stub is enough to configure the trusted publisher; the staged `0.0.0` can be discarded.
+
 Then on npmjs.com → `coreslopper` → Settings → **Trusted publishing** → GitHub Actions:
 
 | Field | Value |

package/runtime/README.md

@@ -72,7 +72,7 @@ cd my-video
 claude
 ```
 
-Run `/mcp` once to authenticate Suno, then `/video-next my-video`. The generated workspace contains the full workflow runtime, so every `npm run cli -- ...` command in this README works inside it. Running `npx coreslopper` without arguments inside a workspace prints the available commands. See [docs/onboarding.md](docs/onboarding.md) for all flags and troubleshooting.
+Run `/mcp` once to authenticate Suno, then `/video-next my-video`. The generated workspace contains the full workflow runtime, so every `npm run cli -- ...` command in this README works inside it. Running `npx coreslopper` without arguments inside a workspace prints the available commands. To move a workspace to a newer release, run `npx coreslopper@latest update` inside it; local edits are kept. See [docs/onboarding.md](docs/onboarding.md) for all flags, updating, and troubleshooting.
 
 ## Quickstarts
 

package/runtime/brand/example/fonts/OFL-SpaceGrotesk.txt

@@ -1,93 +1,93 @@
-Copyright 2020 The Space Grotesk Project Authors (https://github.com/floriankarsten/space-grotesk)
-
-This Font Software is licensed under the SIL Open Font License, Version 1.1.
-This license is copied below, and is also available with a FAQ at:
-http://scripts.sil.org/OFL
-
-
------------------------------------------------------------
-SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
------------------------------------------------------------
-
-PREAMBLE
-The goals of the Open Font License (OFL) are to stimulate worldwide
-development of collaborative font projects, to support the font creation
-efforts of academic and linguistic communities, and to provide a free and
-open framework in which fonts may be shared and improved in partnership
-with others.
-
-The OFL allows the licensed fonts to be used, studied, modified and
-redistributed freely as long as they are not sold by themselves. The
-fonts, including any derivative works, can be bundled, embedded, 
-redistributed and/or sold with any software provided that any reserved
-names are not used by derivative works. The fonts and derivatives,
-however, cannot be released under any other type of license. The
-requirement for fonts to remain under this license does not apply
-to any document created using the fonts or their derivatives.
-
-DEFINITIONS
-"Font Software" refers to the set of files released by the Copyright
-Holder(s) under this license and clearly marked as such. This may
-include source files, build scripts and documentation.
-
-"Reserved Font Name" refers to any names specified as such after the
-copyright statement(s).
-
-"Original Version" refers to the collection of Font Software components as
-distributed by the Copyright Holder(s).
-
-"Modified Version" refers to any derivative made by adding to, deleting,
-or substituting -- in part or in whole -- any of the components of the
-Original Version, by changing formats or by porting the Font Software to a
-new environment.
-
-"Author" refers to any designer, engineer, programmer, technical
-writer or other person who contributed to the Font Software.
-
-PERMISSION & CONDITIONS
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of the Font Software, to use, study, copy, merge, embed, modify,
-redistribute, and sell modified and unmodified copies of the Font
-Software, subject to the following conditions:
-
-1) Neither the Font Software nor any of its individual components,
-in Original or Modified Versions, may be sold by itself.
-
-2) Original or Modified Versions of the Font Software may be bundled,
-redistributed and/or sold with any software, provided that each copy
-contains the above copyright notice and this license. These can be
-included either as stand-alone text files, human-readable headers or
-in the appropriate machine-readable metadata fields within text or
-binary files as long as those fields can be easily viewed by the user.
-
-3) No Modified Version of the Font Software may use the Reserved Font
-Name(s) unless explicit written permission is granted by the corresponding
-Copyright Holder. This restriction only applies to the primary font name as
-presented to the users.
-
-4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
-Software shall not be used to promote, endorse or advertise any
-Modified Version, except to acknowledge the contribution(s) of the
-Copyright Holder(s) and the Author(s) or with their explicit written
-permission.
-
-5) The Font Software, modified or unmodified, in part or in whole,
-must be distributed entirely under this license, and must not be
-distributed under any other license. The requirement for fonts to
-remain under this license does not apply to any document created
-using the Font Software.
-
-TERMINATION
-This license becomes null and void if any of the above conditions are
-not met.
-
-DISCLAIMER
-THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
-OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
-COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
-DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
-OTHER DEALINGS IN THE FONT SOFTWARE.
+Copyright 2020 The Space Grotesk Project Authors (https://github.com/floriankarsten/space-grotesk)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/runtime/docs/adr/0010-npx-onboarding.md

@@ -1,6 +1,7 @@
 # npx onboarding with a versioned runtime snapshot
 
 > Extended by [ADR 0011](0011-higgsfield-provider.md): onboarding also checks and stores Higgsfield credentials.
+> Extended by [ADR 0012](0012-workspace-update.md): workspaces are updated with `coreslopper update`, not `init --force`.
 
 **Status:** Accepted
 

package/runtime/docs/adr/0012-workspace-update.md

@@ -0,0 +1,27 @@
+# Update workspaces with a recorded baseline
+
+## Status
+
+Accepted — 2026-11-08
+
+## Context
+
+A workspace is a runtime snapshot, not a git clone (ADR 0010). Until now the only way to pick up a newer workflow was `npx coreslopper@latest init . --force`, which copies the runtime over the workspace. That overwrites every local edit to a skill, command, or config file, and it never deletes a file that upstream removed, so stale skills keep loading in Claude Code.
+
+## Decision
+
+Add `npx coreslopper@latest update [dir]`, a three-way merge between the recorded baseline, the workspace, and the new runtime.
+
+- `init` and `update` store the SHA-256 of every installed runtime file in `coreslopper.workspace.json` (`files`). This is the **baseline**.
+- A file unchanged since the baseline follows upstream: it is updated, or deleted when upstream removed it.
+- A locally changed file is kept. When upstream changed it as well, the new version is written next to it as `<file>.coreslopper-new` for a manual merge; `--force` overwrites instead.
+- `projects/**` is user-owned: missing upstream files are added, but nothing is overwritten or deleted. `.env`, `.mcp.json`, `GETTING_STARTED.md`, and the marker itself are never touched. `package-lock.json` always follows upstream, because `npm install` rewrites it locally.
+- A downgrade is refused unless `--force` is passed. `--dry-run` reports without writing.
+- A workspace created before this ADR has no baseline. Every file that differs from upstream is then a conflict; the user commits and runs `update --force` once, which records the baseline.
+
+## Consequences
+
+- Updating keeps local customizations and removes obsolete workflow files.
+- The marker grows by one hash per runtime file (about 200 entries) and is committed with the workspace.
+- `init --force` remains for repairing a workspace but is no longer the documented update path.
+- There is no line-level merge; a file changed on both sides needs a manual merge of the `.coreslopper-new` copy.

package/runtime/docs/adr/README.md

@@ -15,5 +15,6 @@ Short records of decisions that are hard to reverse, surprising without context,
 | [0009](0009-mit-open-source.md) | MIT open source with explicit third-party notices. |
 | [0010](0010-npx-onboarding.md) | npx onboarding with a versioned runtime snapshot. |
 | [0011](0011-higgsfield-provider.md) | Higgsfield as a second provider; per-project provider selection and role alternatives. |
+| [0012](0012-workspace-update.md) | `coreslopper update` merges a new runtime against a recorded baseline. |
 
 Status values: `Accepted`, `Deprecated`, `Superseded by ADR-NNNN`.

package/runtime/docs/glossary.md

@@ -9,9 +9,13 @@ A self-contained directory created by `npx coreslopper init` that holds the work
 _Avoid_: repo, checkout
 
 **Runtime Snapshot**:
-The versioned copy of the workflow files that `npx coreslopper init` writes into a workspace. It is not a git clone and is updated by re-running init.
+The versioned copy of the workflow files that `npx coreslopper init` writes into a workspace. It is not a git clone and is updated with `npx coreslopper@latest update`, which merges against the **Baseline**.
 _Avoid_: install, template
 
+**Baseline**:
+The SHA-256 of every runtime file as last installed, stored in `coreslopper.workspace.json`. `coreslopper update` compares it with the workspace to tell local edits from untouched workflow files.
+_Avoid_: lockfile, manifest
+
 **Brief**:
 The one-page statement of topic, source, audience, length, formats, and style that anchors every later creative decision.
 _Avoid_: concept, pitch

package/runtime/docs/onboarding.md

@@ -147,15 +147,36 @@ The base install is enough for the motion-only demo and for projects that import
 
 ## Updating a workspace
 
-The workspace is a snapshot. To pick up a newer workflow version, commit your projects first, then merge the runtime in place:
+The workspace is a snapshot. Pick up a newer workflow version with `update`, run from inside the workspace. Commit first, so `git diff` shows exactly what the update changed:
 
 ```bash
-npx coreslopper@latest init . --force --skip-project --no-install
-npm install
-npm run python:sync
+git add -A && git commit -m "chore: before coreslopper update"
+npx coreslopper@latest update --dry-run   # optional: preview
+npx coreslopper@latest update
 ```
 
-This replaces the workflow files (skills, commands, config, packages, scripts, docs) but leaves your project artifacts under `projects/<your-slug>/` and your `.env` untouched. It merges files; workflow files removed upstream are not deleted from the workspace.
+`update` compares three states per file: the **baseline** recorded in `coreslopper.workspace.json` at the last init or update, your workspace, and the new runtime.
+
+| Your file | Upstream | Result |
+|---|---|---|
+| unchanged | changed | updated |
+| unchanged | removed | deleted |
+| changed | unchanged | kept |
+| changed | changed | kept; new version written as `<file>.coreslopper-new` |
+| changed | removed | kept |
+| deleted | any | stays deleted |
+
+Merge each `.coreslopper-new` file into the original and delete it. `--force` overwrites changed files instead.
+
+`projects/` belongs to you: `update` adds new upstream files there but never overwrites or deletes anything. `.env`, `.mcp.json`, and `GETTING_STARTED.md` are never touched. `package-lock.json` always follows upstream. Afterwards `update` runs `npm install` and `uv sync`; pass `--no-install` to skip them.
+
+| Flag | Effect |
+|---|---|
+| `--dry-run` | List the changes without writing anything. |
+| `--force` | Overwrite locally changed files; also allows a downgrade. |
+| `--no-install` | Skip `npm install` and `uv sync`. |
+
+Workspaces created before `update` existed have no baseline, so every file that differs from upstream counts as a conflict. Commit, then run `npx coreslopper@latest update --force` once; it records the baseline for later updates.
 
 ## Troubleshooting
 

package/runtime/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "coreslopper",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "coreslopper",
-      "version": "0.0.0",
+      "version": "0.2.0",
       "license": "MIT",
       "workspaces": [
         "packages/*"

package/runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coreslopper",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "private": true,
   "type": "module",
   "description": "An open-source, Claude Code-native workflow for producing music videos from brief to render.",

package/runtime/packages/cli/src/init.ts

@@ -5,6 +5,7 @@ import { homedir } from 'node:os';
 import { basename, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
 import { ValidationError } from '@coreslopper/core';
 import { createProject } from './new-project.js';
+import { SKIPPED_DIRECTORIES, hashRuntime } from './update.js';
 import {
   commandExists,
   detectTools,
@@ -59,20 +60,6 @@ export interface InitResult {
   warnings: string[];
 }
 
-const SKIPPED_DIRECTORIES = new Set([
-  '.git',
-  '.cache',
-  '.tools',
-  '.vitest',
-  '.venv',
-  '__pycache__',
-  '.pytest_cache',
-  'node_modules',
-  'dist',
-  'runtime',
-  'tmp',
-]);
-
 export function sanitizeSlug(value: string): string {
   const slug = value
     .toLowerCase()
@@ -188,12 +175,13 @@ function writeFileSyncJson(path: string, value: unknown): void {
   writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
 }
 
-function writeMarker(target: string, projectSlug?: string): void {
+function writeMarker(target: string, files: Record<string, string>, projectSlug?: string): void {
   const marker: WorkspaceMarker = {
     version: 1,
     runtimeVersion: ownVersion(),
     created: new Date().toISOString(),
     ...(projectSlug ? { project: projectSlug } : {}),
+    files,
   };
   writeFileSyncJson(join(target, WORKSPACE_MARKER), marker);
 }
@@ -343,7 +331,7 @@ export async function initWorkspace(options: InitOptions): Promise<InitResult> {
     ? await createFirstProject(target, options.project, warnings)
     : undefined;
 
-  writeMarker(target, projectSlug);
+  writeMarker(target, await hashRuntime(runtime), projectSlug);
 
   let installed = false;
   let uvSynced = false;

package/runtime/packages/cli/src/npx.ts

@@ -9,6 +9,7 @@ import {
 import { createProject } from './new-project.js';
 import { onboard } from './onboarding.js';
 import { printStatus } from './status.js';
+import { printUpdateSummary, updateWorkspace } from './update.js';
 import { formatSeconds, run } from './utils.js';
 import { validateProject } from './validate.js';
 import {
@@ -50,7 +51,7 @@ function workspaceSummary(root: string): void {
   } else {
     console.log('No projects yet. Create one with: npx coreslopper new <slug> --budget 50');
   }
-  console.log('Commands: init, doctor, new, status, validate');
+  console.log('Commands: init, update, doctor, new, status, validate');
 }
 
 const program = new Command();
@@ -96,6 +97,32 @@ program
     }),
   );
 
+program
+  .command('update [dir]')
+  .description('Update the workflow files of a workspace to this coreslopper version; keeps local changes.')
+  .option('--dry-run', 'Show what would change without writing anything')
+  .option('--force', 'Overwrite locally changed files and allow a downgrade')
+  .option('--no-install', 'Skip npm install and uv sync')
+  .option('--runtime <dir>', 'Runtime directory (development only)')
+  .action(
+    (
+      dir: string | undefined,
+      options: { dryRun?: boolean; force?: boolean; install: boolean; runtime?: string },
+    ) =>
+      run(async () => {
+        const target = dir ? resolve(dir) : requireWorkspaceRoot();
+        const result = await updateWorkspace({
+          targetDir: target,
+          runtimeDir: options.runtime,
+          dryRun: options.dryRun,
+          force: options.force,
+          install: options.install,
+          onProgress: (message) => console.log(message),
+        });
+        printUpdateSummary(result);
+      }),
+  );
+
 program
   .command('doctor [dir]')
   .description('Check the workspace, tools, and credentials.')