@aiccapp/aicc
v0.5.0
Published
Standalone AICC Workspace local development CLI, connector and relay
Readme
AICC Workspace Local Dev
Standalone CLI and outbound development Relay. Version 0.4.3 supports Node
22.19 or later in 22.x, 24.x, and 25.x (>=22.19 <23 || >=24 <26). Node 23
and 26 or later are not supported. Developers install this package without
Codex, Java, MySQL, Redis, or the personal App Server skill. The default native
runtime needs no Docker; the optional Docker runtime requires a running local
Docker Engine or Docker Desktop.
Platform login, access checks, model providers and billing stay in the cloud.
For the deployed platform, see the Chinese installation and usage guide.
Install and run
Install the published CLI from the official scoped package:
npm install --global @aiccapp/[email protected]
aicc --helpMaintainers build and publish only the compiled release/ directory. The package
contains the bundled shared Pi Web component and session core; users do not need
the source repository or a separate Pi Web installation.
aicc login --platform https://app.aiccapp.com/api
# Approve the displayed device code in the platform while signed in.
aicc create --name "My application" --path ./my-application
cd my-application
aicc dev
aicc deploy -m "Describe the change"
aicc releasecreate provisions the Workspace and first Draft through the platform API,
clones its Draft branch, links the checkout, and pulls development settings.
deploy runs preflight, pushes the Draft, builds Preview, and waits for it to
become ready. release requires explicit confirmation, waits for the immutable
Release to become active, and prints its permanent URL.
Existing checkouts can still use aicc link; env pull, config pull,
status, logs, and stop remain available for diagnostics.
link infers the platform when exactly one unexpired CLI login is saved; use
--platform when several accounts/platforms exist. Git clone/push uses the
existing Git credential flow. Git PATs do not grant CLI, configuration or model
access. aicc login creates an independent management credential with a browser
approval and stores it outside the project in ~/.config/aicc/credentials.json
(directory 0700, file 0600). AICC_CONFIG_DIR overrides this location.
Next time, run aicc dev. The terminal prints the local Node version, platform
runtime, authenticated HTTPS preview address, app address, local data directory
and process logs. aicc status reports
the current lease, active streams and Worker runs; aicc logs prints the bounded
local log; aicc stop or Ctrl+C stops the app, connector and Worker and revokes
the cloud session. aicc logout also revokes the CLI credential and its sessions.
With the default --runtime native, app.yaml is read from the checkout root,
or app/app.yaml when there is no root
manifest. The application starts in the manifest directory. It supports the
existing runtime: node22 contract: shell-free commands.dev node/npm argument array,
port (default 3000), health.path (default /healthz) and health timeout.
HOST=127.0.0.1 and PORT are injected. A local-only Node preload also forces
ordinary TCP servers to bind 127.0.0.1, including existing App code that uses
0.0.0.0, ::, or omits the host. npm and watch child processes inherit the
preload; Unix sockets remain unchanged. This compatibility adaptation is not a
sandbox for application code or native executables. --port explicitly overrides an occupied
port. Existing listeners are never terminated or adopted. Startup waits up to
60 seconds for app health. Hot reload is supplied by the app's commands.dev
(for example node --watch server.js or Vite); Relay carries WebSocket HMR.
Node 24 and 25 support was added in 0.3.1. The local App and Worker use the same
Node executable as the CLI. Their child processes inherit a PATH that resolves
node to that runtime. The manifest's
runtime: node22 remains the platform deployment target; it does not switch the
local process to Node 22. When developing on Node 24 or 25, verify the application
and its dependencies on Node 22.19 or later in 22.x before publishing. A macOS
run on Node 24/25 does not reproduce the platform's Linux/Node 22 environment.
Use the Docker profiles below to verify Linux/Node 22 execution before publishing.
Native aicc dev --inspect prints a loopback Node Inspector address on a dynamically
allocated port. Attach an IDE or DevTools to that address. The App starts with
--inspect, not --inspect-brk; it does not automatically pause before execution.
App breakpoints leave CLI renewal and tunnel handling running. Local Worker
application commands use separate fresh Node processes with loopback Inspector
and break before execution, so breakpoints can be set before the current source
is loaded. Inspectors never enter the public tunnel.
Docker development and release checks
Native development remains the default. Docker mode runs the App, local Worker and shared Pi session engine together in an isolated Linux/amd64 container with the Node 22 release specified by the bundled Dockerfile. Apple Silicon runs this architecture through Docker's emulation. The host CLI still needs a supported Node version and a local Docker context; remote Docker contexts are not supported.
# Editable source, app.yaml commands.dev, automatic App reload.
aicc dev --runtime docker --profile preview --port 3005 --allow-shell
# Stop the previous session before checking the release startup path.
aicc stop
aicc dev --runtime docker --profile release --port 3005 --allow-shellpreview is the default Docker profile. It mirrors current source, including
uncommitted edits, into a read-only container mount. After each synchronized batch,
the CLI sends a control message to reload App and recheck health, so missed Docker
filesystem notifications cannot leave the server running stale modules. Direct
Node --watch flags are replaced by this managed reload. Worker/Pi sessions,
the container, preview connection and data stay alive. aicc status reports
RELOADING, then READY, with sourceRevision and appliedSourceRevision;
startup errors after an edit report ERROR and can recover on the next edit.
The mirror excludes .git, .aicc, .env*, package-manager
credentials, host node_modules and local build caches. Do not place runtime
databases or credentials in ordinary source files.
This reload control was added in 0.4.1. Installing a CLI update does not modify an
already running container; the next aicc dev session loads the new runtime.
release builds a source snapshot with commands.build, when declared, and
starts commands.start; later host edits do not alter that running snapshot.
It is a local verification profile and does not create or publish a platform
Release. Stop and rerun development after changing app.yaml, package.json
or package-lock.json so the image and Linux dependencies are rebuilt.
The first Docker startup builds the packaged runtime and installs application
dependencies in Linux. Apps with dependencies require a committed
package-lock.json; npm ci runs during image preparation. Host dependencies
are never mounted into the container. Source and installed dependencies remain
read-only at runtime, so framework caches must use the writable App data
directory or temporary storage. Docker mode currently rejects --inspect and
--allow-project-write; use native mode when those controls are needed.
App data and Pi history use persistent Docker volumes scoped to the linked
platform, tenant, Workspace, Draft and profile. Preview and release checks use
separate data, and both are separate from native .aicc/data. aicc stop
removes the running container and revokes the development session while keeping
these volumes. The container publishes only the selected 127.0.0.1 port and
does not mount the Docker socket or the developer's home directory.
Docker bash uses the same Pi SDK tool definition, result/truncation format,
process cancellation, environment filtering and command timeout policy as
hosted App bash: parameters are command and optional timeout, with the
working directory fixed to App source. Do not pass native-only directory or
cwd. Its timeout defaults to 60 seconds, capped at 300 seconds for ordinary
commands and 900 seconds for recognized build/test commands; the enclosing
Worker run deadline still applies. Other file/application tools retain their
existing rooted local contracts.
The App and tools receive AICC_LOCAL_DEV=true and
AICC_RUNTIME_PROFILE=platform. The first selects development identity and
session semantics; the second selects the platform command contract. In
particular, a Docker Work Agent result still exposes its actual Pi session as
agentSessionId, while sessionId identifies the development connection.
Apps that distinguish native/hosted bash arguments should also read the runtime
profile, without changing how they pass the incoming request to the identity
and Work Agent SDKs.
Docker keeps the same LOCAL_DEV cloud authorization, viewer identity, model
access and billing as native development. Management and Relay credentials
stay in the host CLI; the container receives scoped, renewable runtime grants.
Online tool grants are still required. --allow-shell authorizes the session,
and --confirm-shell optionally adds a terminal decision for every command;
neither expands cloud permissions. The CLI never supplies production signing
keys to the container.
This mode shares execution contracts and Linux dependencies with platform development, but it is not a byte-for-byte copy of the hosted runtime image. It uses the packaged local Worker and shared Pi core with development grants; the hosted gateway, Supervisor, deployment image and release policies remain platform services. Complete the normal cloud Preview and Release checks before claiming deployment parity.
Shared application assistant in 0.3.0
The assistant identity and business-role prompt also come from the shared Pi Web
appAssistantPrompt generator. Local execution changes the runtime facts and
effective tool descriptions; it does not select a separate Worker persona.
A read-only test configuration remains read-only.
Version 0.3.0 embeds the same AppAssistant, ChatWindow and useAgentSession
used by the platform App assistant. It uses the shared Pi SDK AgentSession and
JSONL session format, with local source/tool execution and cloud identity,
model access and billing. It replaces the separate 0.1.1 task panel. No Next
server or separate Pi Web installation is required on a developer's machine.
Configure the assistant in the platform's application settings. aicc config pull
downloads its enabled state, tool/file permissions, confirmation policy and
effective model list/default to private .aicc/assistant.config.json. Every
aicc dev fetches a fresh snapshot automatically; a failed fetch stops startup
instead of trusting an older cache. This requires the matching platform backend
with /workspace/local-dev/cli/assistant-config support.
Cloud settings override the local manifest's assistant runtime settings without
rewriting app.yaml. Local systemPromptFile and skills remain unchanged, so
role and Skill development still uses the current checkout. --tools can only
narrow cloud tools. --allow-shell grants local shell consent for the current
development session; add --confirm-shell to require a local terminal decision
for each command.
For business commands, implement the registry described in
worker/README.md. Enabling the UI creates no business
commands and grants no extra tools.
Open the HTTPS Preview from the platform and click AI 助手. The same
conversation now carries previous turns; the shared component renders streamed
text, tool activity, model selection, cancellation and errors. Selected main
conversations use chatSession in the assistant URL, with an opaque id saved in
the current server-issued viewer scope for whole-page refresh. session remains
the Worker viewer parameter and does not replace that main selection. Restoring a conversation reads its JSONL only after the API
validates its owner against the current signed-in viewer. Unknown or forbidden
main conversation ids are cleared before a new conversation is shown. Closing
the panel does not stop a running conversation. No model prompt starts merely
because the page or panel is opened.
The local runtime currently declares attachments: false: the shared composer
hides uploads and does not accept pasted/dropped files. Hosted assistants without
that capability restriction keep their attachment controls. This does not turn
on Builder-only controls, plugin management or arbitrary host filesystem access.
When a tool requires confirmation, approval happens in the local aicc dev
terminal. The browser cannot approve a local write or shell command. A refusal
or unavailable terminal is reported by the tool; obtain the required local
authorization before retrying. In 0.3.2, shell runs authorized by --allow-shell
do not prompt unless --confirm-shell is also set. Business writes retain the
online requireConfirmation policy.
Background Work Agent SDK tasks use the same session engine while retaining
their run/status/wait contract. Their bounded in-memory run records do not become
a durable job queue simply because the AgentSession writes JSONL.
The bridge injects a small launcher into eligible HTML without changing App
source. The iframe, API, JavaScript, CSS and icons use
/_aicc/local-dev/assistant. The bundle's lexical fetch and EventSource
adapters route its API calls there without overriding window.fetch or taking
over the App's /api, /_next or /icons paths. Browser assets contain no Worker
capability, cloud credential or signing secret. The bridge validates the actual
browser invocation and never substitutes the developer when it is missing.
The raw 127.0.0.1:<app-port> address serves the App directly, with no automatic
assistant injection or browser cloud identity. Use the authorized HTTPS Preview
for the complete flow. After changing assistant.enabled, restart aicc dev;
its startup output and aicc status report whether the assistant is enabled.
If the button is missing, inspect aicc logs and the HTML response's
x-aiapp-local-assistant-status header:
| Status | Meaning |
| --- | --- |
| READY | The launcher was injected; this alone does not prove a model/tool call. |
| ASSISTANT_CSP_BLOCKED | The App policy cannot safely support the injected launcher/frame. |
| UNSUPPORTED_HTML_ENCODING | Compressed HTML despite an identity request, or unsupported character encoding. |
| HTML_TOO_LARGE | HTML exceeds the 5 MiB injection limit. |
The bridge preserves the App's CSP and passes unsupported pages through with a
diagnostic. It does not add unsafe-inline or weaken policy. A
BROWSER_AUTH_REQUIRED error means to open the authorized Preview and sign in;
never copy a Worker credential into frontend code.
Configuration and local capabilities
.aicc/project.json contains only platform/tenant/workspace/draft identifiers.
env pull writes only explicitly authorized LOCAL_DEV configuration to the
git-ignored .aicc/env.local.json with mode 0600. Withheld secrets are reported
by count; there is no SHARED or production fallback. Reserved runtime variables
cannot be supplied through this configuration. Run env pull, then restart
dev, after changing development values. Third-party test secrets require their
own export grants. Provider keys and platform signing keys stay in the cloud.
Chat JSONL and owner records live under .aicc/assistant-state/<scope>/, scoped
to platform, tenant, Workspace, Draft and viewer. They are not synchronized to
the online assistant. Runtime data is .aicc/data/<workspaceId>/<draftId> and is exposed through
AICC_APP_DATA_DIR. No production data is downloaded. Data, environment, logs,
control socket and run state are git ignored. Log size is bounded at 2 MiB,
known credentials/configuration values are redacted across child stdout chunks,
and oversized lines are omitted. Application authors must still avoid logging
unknown secrets or deliberately encoded credentials.
Relay/model/worker cloud credentials rotate in CLI memory on each independent
heartbeat. App model calls use an ephemeral loopback proxy with
OPENAI_BASE_URL/OPENAI_API_KEY, also provided as
AICC_MODEL_BASE_URL/AICC_MODEL_TOKEN and
WORKSPACE_MODEL_BASE_URL/WORKSPACE_MODEL_TOKEN. The proxy injects the current
cloud model token and streams cancellation/backpressure end to end. Local
credentials are not written to .env or project configuration.
Each cloud model call also carries a generated request UUID. Client aborts send
an authenticated cancellation request with the current model token, including
when the provider has sent no headers or has stopped producing bytes. The
cancellation has its own bounded timeout and one transient retry; normal
completion sends none. This requires the matching platform cancellation API.
An app enabled in the online assistant settings gets the bundled local Worker automatically.
The existing server Work Agent SDK uses AICC_WORKER_AGENT_ENDPOINT and
AICC_WORKER_AGENT_TOKEN; use SDK 1.1's { request } option so the true browser
invocation grant reaches the Runner. A local token alone cannot invent a visitor.
Worker capabilities are the intersection of current online policy, the development
session's original grant and CLI requests (--tools read,app_data_read,...).
Heartbeats refresh the runtime snapshot; tool/model calls recheck current cloud
policy. Restart development after enabling the assistant or adding tools to a
running session. Removing a permission cannot be bypassed by an old snapshot.
Project file tools are read-only by default in native mode;
--allow-project-write adds local consent but cannot widen cloud grants. Docker
source is mounted read-only and does not support that flag. Mutating
file and business tools follow the cloud confirmation policy; noninteractive
runs return NEEDS_HUMAN when confirmation is required. The Worker provides create/status/
cancel/wait with status polling. Run state remains in memory; the shared
AgentSession writes persistent JSONL without promising interrupted-job resume. See
worker/README.md for its tool and trust boundaries.
Current approved assistant.skills and role files are loaded from the local
checkout, including uncommitted edits. Bash additionally requires the current
online agent.shell grant and aicc dev --allow-shell. In 0.3.2, that flag
allows authorized bash commands to run automatically for the current development
session, matching the online bash approval behavior. The online general
requireConfirmation setting does not control bash. Without --allow-shell,
bash is not exposed to the model. To require per-command terminal confirmation,
use aicc dev --allow-shell --confirm-shell; --confirm-shell is invalid without
--allow-shell. Required confirmation is rejected when no interactive terminal
is available, while --allow-shell alone can run under a background supervisor
such as App Server. These flags do not widen cloud permissions or change
business-write approval. Native shell code runs with your OS account's access;
Docker shell code runs inside the configured container and mounts.
Commit and push through the existing Builder sync → cloud Preview → new Release flow. Local Dev never changes PREVIEW's endpoint, publishes a Release, or uploads local data. Independent sessions on the same Draft get different random routes.
Cloud Relay deployment
Deploy the same tarball's aicc-relay process on the platform side. It opens only
outbound connections to the Java control plane. Developers connect outbound WSS
to its public /connect endpoint; browser traffic first passes Runtime Gateway.
AICC_PLATFORM_URL=https://internal-platform.example/api \
AICC_INTERNAL_TOKEN=<cloud-internal-service-token> \
AICC_RELAY_GATEWAY_SECRET=<at-least-32-byte-cloud-service-secret> \
HOST=127.0.0.1 PORT=6090 aicc-relayUse TLS termination for the public WSS endpoint. The TLS proxy must support
WebSocket upgrade, disable HTTP/SSE buffering, preserve streaming cancellation,
and allow long connections. The internal HTTP ingress must be reachable only by
Runtime Gateway; configure Gateway
RUNTIME_GATEWAY_LOCAL_DEV_ENABLED=true and
RUNTIME_GATEWAY_LOCAL_DEV_RELAY_KEY to the same Relay service secret. Configure
Java's workspace.local-dev.relay-url to the public wss://.../connect,
relay-internal-url to the cloud Relay HTTP root, platform-url to the API
base (including /api when applicable), and the LOCAL_DEV feature flag/policies
and reviewed database migration described in the project deployment document.
The internal token is the existing Java workspace.builder.internal-token.
Neither service secret is given to a developer.
Gateway sends X-AICC-Dev-Session plus X-AICC-Relay-Key, preserves the path, and
replaces all untrusted identity headers with the verified browser context. Relay
strips its service key/session-control headers before sending requests locally.
When the assistant is disabled, the connector only requests
127.0.0.1:<spawned-app-port>. When enabled, it connects to the CLI-created
loopback assistant bridge, which serves the reserved component/API paths and
forwards App requests to that fixed App port. The bridge's Worker destination
is also fixed at startup. These proxies follow no redirects; neither browser
nor cloud frames can register another upstream. App WebSockets still pass
through to the App.
Every request and each five-second connection refresh revalidates the cloud
session, Draft, membership and originating login. Lease and credential expiry,
disconnect, revocation or control-plane failure close all in-flight requests and
WebSockets. The CLI closes local app/model/Worker services on heartbeat failure.
The Relay defaults to 1024 sessions, 32 streams per session, 128 KiB WebSocket
messages, 256 KiB directional stream windows, 64 in-flight handshakes and ten
minutes per HTTP request. Reverse-proxy limits should be consistent. One process
owns each session; run a single Relay or provide deterministic affinity shared by
the public connector and Gateway ingress. This version does not implement a
distributed Relay session bus or automatic reconnect; after network recovery run
aicc dev to create a fresh route.
For a planned rollback, first disable Gateway LOCAL_DEV routing and stop Relay ingress. Keep Java LOCAL_DEV enabled while revoking existing sessions through their authorized Java API; confirm revocation, then disable Java LOCAL_DEV. Emergency Java disablement blocks access immediately, but normal session revocation APIs are unavailable while that flag is off.
Retain the added tables, columns, indexes, configuration and audit data on rollback. Any later removal requires every new JAR instance to have been reverted and a separately reviewed migration; retaining the schema is recommended. Existing cloud Preview/Release infrastructure is independent. Installing this npm package performs no migration or production deployment.
Verification
Run the build and CLI regression suite on supported Node 22.19+ (22.x), 24.x, and 25.x when changing runtime compatibility. Verify Node 23 and 26 or later are rejected. Application release checks must still use the platform's Node 22 runtime, even when local development uses a higher supported version.
npm test exercises real forked applications, HTTP duplex transfer, early SSE,
browser cancellation, text/binary WebSocket HMR, paused-client backpressure,
revocation, real CLI login/link/env/dev/status/logs/stop, actual Inspector pauses
while heartbeats continue, uncommitted watch reload, rotating model tokens and
Worker dirty-source execution/path authorization. Its control-plane/model
fixtures are deterministic test doubles. The separate repository acceptance
runner exercises the Java control plane and Gateway against an isolated local
database; its model provider is explicitly a fixture, not paid-cloud evidence.
The 0.3.0 assistant checks cover the shared frontend transport, selected-session
authorization and restoration, stream/cancellation handling, CSP diagnostics,
and the App/Worker/assistant bridge with fixtures. Those tests alone do not establish production browser or paid-cloud
acceptance.
The optional Linux Docker acceptance test builds the standalone runtime image and runs actual App, Pi sessions, Worker tools and shutdown paths:
npm run build
AICC_DOCKER_TEST=1 node --test test/docker-e2e.test.mjs
# To verify an isolated installation of the npm tarball:
AICC_DOCKER_TEST=1 AICC_TEST_CLI=/path/to/install/node_modules/@aiccapp/aicc/cli/aicc.mjs \
node --test test/docker-e2e.test.mjsIt requires a local Linux Docker engine and npm, uses a bundled fixture dependency
to verify Linux installation and excludes host node_modules. It checks preview
hot reload, immutable release build/start, read-only source/dependencies, writable
and profile-isolated data, viewer authorization, the platform bash schema and
container/port cleanup. Cloud introspection and model responses run in a separate
test-only image wrapper; no real credentials or paid model calls are involved.
The normal test suite skips this test unless AICC_DOCKER_TEST=1 is set.
For local acceptance only, CLI --insecure-loopback permits HTTP platform and
WS Relay URLs whose host is loopback. Production and non-loopback addresses
require HTTPS/WSS. Local app source runs with the developer's operating-system
permissions; directory checks are not a container sandbox. Unix/macOS control
uses a private socket. Windows has named-pipe control but process-tree shutdown
and filesystem ACL behavior still require validation before claiming parity.
设备授权持续有效
新批准的 aicc login 设备授权不再按 8 小时自动过期,也不会因为浏览器登录凭证自然到期而中断开发。aicc logout、批准该设备的平台登录主动退出、踢下线或被替换仍会撤销授权。旧的有期限设备授权需要重新执行一次 aicc login 才会使用新规则。短期运行凭证仍由心跳刷新;停止心跳、权限被移除、草稿归档或发布新版本仍会结束当前运行会话。
服务器上的 Workspace App 可在应用设置的“运行资源”中配置 CPU 核心、内存(MiB)和 GPU 数量。保存并重建运行容器后用于预览与正式 App,不重新发布应用代码;GPU 需由运行节点的 NVIDIA Container Toolkit 提供。
Draft 显示编号与全局 ID
每个 Workspace 独立显示 Draft 1、Draft 2 等编号。新 CLI 输出例如 Draft 1 (ID 56);aicc link --workspace 39 --draft 56、Git 分支 draft/56 和 .aicc/project.json 中的 draftId 仍使用全局 ID 56。可选的 draftNo 只用于显示,旧版 CLI 和既有项目文件继续兼容。旧项目重新 link 后可取得显示编号;未取得时明确显示 Draft ID 56。此功能尚未发布到 npm。
设备授权持续有效
新批准的 aicc login 设备授权不再按 8 小时自动过期,也不会因为浏览器登录凭证自然到期而中断开发。aicc logout、批准该设备的平台登录主动退出、踢下线或被替换仍会撤销授权。旧的有期限设备授权需要重新执行一次 aicc login 才会使用新规则。短期运行凭证仍由心跳刷新;停止心跳、权限被移除、草稿归档或发布新版本仍会结束当前运行会话。
服务器上的 Workspace App 可在应用设置的“运行资源”中配置 CPU 核心、内存(MiB)和 GPU 数量。保存并重建运行容器后用于预览与正式 App,不重新发布应用代码;GPU 需由运行节点的 NVIDIA Container Toolkit 提供。
查看已发布应用的容器
这些命令只读正式运行容器,不会启动、重建或切换应用。需要 aicc login,且当前账号仍是 Workspace 管理员。可以在已关联的项目目录运行,也可以指定 Workspace:
aicc status --online --workspace 52
aicc status --online --workspace 52 --region cn1
aicc logs --online --workspace 52 --region cn1 --tail 200
aicc logs --online --workspace 52 --region hk --tail 200status --online 显示各地区正式容器的状态、CPU/内存用量及实际资源限制;加 --region 只查看指定地区。logs --online 默认香港,返回当前正式版本最近 200 行 stdout/stderr(含时间戳),允许 1–1000 行,每次最多 1 MiB。没有正式实例或采集失败会明确报错,不会转而读取其他地区。默认 aicc status 和 aicc logs 仍查看本地开发服务。日志是一次性快照,并非持续跟随。
Contract-based tasks
aicc task validate --file skill.contract.json validates a trusted Skill contract without executing it. aicc task run --file skill.contract.json --inputs inputs.json --allow-shell executes its bounded linear steps, independently verifies each output, and delivers only declared artifacts. Use aicc task status RUN_ID, resume RUN_ID --allow-shell, and artifacts RUN_ID to inspect, recover and verify delivery. Existing shell authorization and container boundaries still apply; this is not a script sandbox.
Inputs and Skill resources are snapshotted in .aicc/tasks/RUN_ID; verified deliverables appear in outputs/tasks/RUN_ID with a versioned manifest. Keep .aicc/ out of source control. A changed checkpoint or an uncertain non-repeatable action stops recovery. Legacy SKILL.md-only Skills remain supported. See contract specification and the repository example examples/contract-report.
