📚 docs(openspec): propose export, import, compare and verify for prompts and assistants

openspec/changes/export-import-prompts-and-assistants/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-13

openspec/changes/export-import-prompts-and-assistants/proposal.md

@@ -0,0 +1,45 @@
+# Export, import, compare and verify prompts and assistants
+
+Issue: [#807 Export, import, compare, and verify prompts and assistants across LangSmith environments](https://github.com/codekiln/langstar/issues/807)
+
+## Why
+
+Moving an application to a new LangSmith workspace and a new deployment means recreating its prompts and its assistants there. Today a user does that by hand in the web interface, or with `langstar prompt push`, which builds a single-message prompt and drops the model, the system message and any placeholders. Nothing checks afterwards that the copy matches the original or that it can still run.
+
+A prompt belongs to a workspace and an assistant belongs to a deployment, but both need the same four operations: write the definition to a file that can live in Git, recreate it somewhere else, compare a copy with that file, and check that the copy has what it needs to run.
+
+## What Changes
+
+- `langstar prompt export <handle>` writes one JSON file holding a saved prompt commit as LangSmith returns it with the model included: message templates, input variables, output schema, structured output method, model binding and commit description, plus the repo's description, readme, tags and visibility, the commit tags, and where it came from.
+- `langstar prompt import <file> --workspace-id <id>` creates the prompt in the destination workspace, or adds a commit to an existing prompt, updates its repo details and creates, moves or deletes its commit tags when the user passes `--update`. An import that stopped before it pushed the first commit finishes on the next run, and one that stopped before it created the commit tags finishes with `--update`. `--dry-run` shows what it would do. After writing, it reads the prompt back and reports any difference.
+- `langstar prompt compare <file>` reports the differences between the file and a prompt in a workspace. `langstar prompt verify <file>` also checks that the workspace has the secrets the prompt's model reads, and notes when the workspace has no saved model configuration for the model's class, such as `ChatOpenAI`.
+- `langstar assistant export`, `import`, `compare` and `verify` do the same for assistants on a deployment. The file holds the name, description, graph ID, configuration, context, metadata and any prompt names the assistant refers to. `verify` checks that the destination deployment has the graph and that the destination workspace has the referenced prompts.
+- `prompt export` and `assistant export` write no file when the prompt or assistant holds a credential. Before writing, export checks every string for a key name such as `api_key`, `token`, `password`, `secret` or `Authorization`, and for a value shaped like a bearer token, a private key, a URL or connection string with a password, a JSON Web Token or a provider's API key. Export names the path of each flagged string and exits with status 1. A user who has read a flagged string and found it harmless passes `--not-a-secret <json-pointer>` to write it. Compare, verify and import print `<redacted>` in place of the same strings.
+- Import records each destination ID (the new commit hash, or the new assistant ID) in a separate file next to the export. When a user imports the same file again, langstar reads that file to find the assistant it created earlier instead of creating another one, and to tell whether someone pushed a commit to the prompt since the last import.
+- Import runs the dependency checks of `verify` before it writes, and writes nothing when one fails.
+- `compare`, `verify` and `import` share one exit status scheme, 0 for a match, 3 for a difference or a failed check and 1 for any other error, and print a JSON report with `-f json`. Status 2 stays clap's usage error.
+
+## Capabilities
+
+### New Capabilities
+
+- `prompt`: the `langstar prompt` command group. This change adds its export, import, compare and verify requirements; the existing prompt subcommands get their requirements when [#728 Implement CRUD command structure (create, get, update) for prompt commands](https://github.com/codekiln/langstar/issues/728) lands.
+
+### Modified Capabilities
+
+- `assistant`: adds export, import, compare and verify requirements to `langstar assistant`.
+
+## Impact
+
+- SDK: `sdk/src/prompts.rs` gains the prompt calls export and import need: a commit read that asks for the model and returns it on `CommitManifestResponse`, a commit create that sends a description and returns the new commit's `id`, a commit list, calls that list, create, move and delete commit tags, and a repo update. `Prompt` gains the repo's readme, tags and `tenant_id`, and export fills `source.workspace_id` from `tenant_id`. `sdk/src/assistants.rs` gains the `context` and `version` fields, `assistant_id` and `if_exists` on create, `graph_id` on update, and a search by graph ID. Developers commit these fields as `✨ feat(sdk)` with no `BREAKING CHANGE:` footer, so the Prepare Release workflow makes the next release a minor version. [design.md's decision on the SDK release](design.md#developers-commit-the-new-sdk-fields-as--featsdk-so-the-next-release-is-a-minor-version) links the release docs that ask for this.
+- CLI: new subcommands in `cli/src/commands/prompt.rs` and `cli/src/commands/assistant.rs`, and a shared module for the export file, the destination record, comparison and the exit status.
+- Tests that copy between environments need a second workspace, a second deployment and one model provider key for the structured output check, and the structured output check skips without the key. Developers run the tests in the single existing workspace and test deployment while they build the commands, and in a second workspace and a second deployment before anyone archives the change, because [#807 Export, import, compare, and verify prompts and assistants across LangSmith environments](https://github.com/codekiln/langstar/issues/807) asks for a copy between environments. Once the second workspace and deployment exist, langstar's tests read them through `fnox.toml` and the CI workflow; the destination deployment fixture from [export-import-prompts-and-assistants Task 2.4 Add a destination deployment fixture](tasks.md#L19) creates the deployment whenever the cleanup workflow has deleted it, as the source fixture does today. Nobody knows yet whether the control plane accepts a second deployment from this repository. In [export-import-prompts-and-assistants Task 2.3 Register the test graph under a second graph ID](tasks.md#L18), a developer deploys the new `langgraph.json` once to find out, before anyone builds the fixture.
+- Docs: a new usage page on moving prompts and assistants between environments.
+
+## Citations
+
+- [My/Principle/Declarative over Imperative](https://github.com/codekiln/logseq-encode-garden/blob/main/pages/My___Principle___Declarative%20over%20Imperative.md)
+- [My/Principle/Explicit is better than Implicit](https://github.com/codekiln/logseq-encode-garden/blob/main/pages/My___Principle___Explicit%20is%20better%20than%20Implicit.md)
+- [My/Principle/Simplify/Create Uniform Interfaces](https://github.com/codekiln/logseq-encode-garden/blob/main/pages/My___Principle___Simplify___Create%20Uniform%20Interfaces.md)
+- [My/Principle/Make the Right Thing Easy and the Wrong Thing Hard](https://github.com/codekiln/logseq-encode-garden/blob/main/pages/My___Principle___Make%20the%20Right%20Thing%20Easy%20and%20the%20Wrong%20Thing%20Hard.md)
+- [My/Principle/Simplify/Prefer Standards and Defaults](https://github.com/codekiln/logseq-encode-garden/blob/main/pages/My___Principle___Simplify___Prefer%20Standards%20and%20Defaults.md)

openspec/changes/export-import-prompts-and-assistants/references/langgraph-sdk.md

@@ -0,0 +1,13 @@
+# LangGraph Python SDK assistants client
+
+Read at [langgraph 8a77332d](https://github.com/langchain-ai/langgraph/tree/8a77332d0db75c49d296b1f3833a3a5ccd5f0dc8).
+
+[`create`](https://github.com/langchain-ai/langgraph/blob/8a77332d0db75c49d296b1f3833a3a5ccd5f0dc8/libs/sdk-py/langgraph_sdk/_async/assistants.py#L314) posts `graph_id`, `config`, `context`, `metadata`, `assistant_id`, `if_exists` (`raise` or `do_nothing`), `name` and `description` to `/assistants`.
+
+[`update`](https://github.com/langchain-ai/langgraph/blob/8a77332d0db75c49d296b1f3833a3a5ccd5f0dc8/libs/sdk-py/langgraph_sdk/_async/assistants.py#L385) patches `graph_id`, `config`, `context`, `metadata`, `name` and `description`, and the server merges `metadata` into the existing metadata. [`get_versions`](https://github.com/langchain-ai/langgraph/blob/8a77332d0db75c49d296b1f3833a3a5ccd5f0dc8/libs/sdk-py/langgraph_sdk/_async/assistants.py#L656) lists the versions updates create.
+
+[`AssistantBase`](https://github.com/langchain-ai/langgraph/blob/8a77332d0db75c49d296b1f3833a3a5ccd5f0dc8/libs/sdk-py/langgraph_sdk/schema.py#L246) returns `assistant_id`, `graph_id`, `config`, `context`, `created_at`, `metadata`, `version`, `name` and `description`. `context` sits beside `config.configurable`; newer graphs read it and older ones read `configurable`.
+
+There is no endpoint that lists graphs. [`search`](https://github.com/langchain-ai/langgraph/blob/8a77332d0db75c49d296b1f3833a3a5ccd5f0dc8/libs/sdk-py/langgraph_sdk/_async/assistants.py#L528) filters by `graph_id`, and every graph has a default assistant with `metadata.created_by` set to `system`, as the [`get` docstring](https://github.com/langchain-ai/langgraph/blob/8a77332d0db75c49d296b1f3833a3a5ccd5f0dc8/libs/sdk-py/langgraph_sdk/_async/assistants.py#L81) shows.
+
+What langstar takes from it: the fields an assistant export carries, including `context`, and the graph check through search.

openspec/changes/export-import-prompts-and-assistants/references/langsmith-cli.md

@@ -0,0 +1,17 @@
+# LangSmith CLI (Go)
+
+Read at [langsmith-cli 26135038](https://github.com/langchain-ai/langsmith-cli/tree/26135038671155f05ddd725703de7bdd43c7aa9f).
+
+[`prompt pull`](https://github.com/langchain-ai/langsmith-cli/blob/26135038671155f05ddd725703de7bdd43c7aa9f/internal/cmd/prompt.go#L301) takes `OWNER/REPO[:COMMIT_OR_TAG]` and writes this envelope to stdout or `--output`:
+
+```json
+{"owner": "...", "repo": "...", "commit_hash": "...", "description": "...", "manifest": {}}
+```
+
+It reads the commit with empty `CommitGetParams`, so the model is never requested.
+
+[`prompt push`](https://github.com/langchain-ai/langsmith-cli/blob/26135038671155f05ddd725703de7bdd43c7aa9f/internal/cmd/prompt.go#L359) reads the bare manifest from `--file` or stdin and sends it as `manifest`, with optional `--parent-commit` and `--description`. It does not create the repo and has no tag flag. A pull envelope fed to push is sent as the manifest itself.
+
+[`resolveClientOptions`](https://github.com/langchain-ai/langsmith-cli/blob/26135038671155f05ddd725703de7bdd43c7aa9f/internal/cmd/root.go#L161) picks one workspace per run from `--workspace`, `LANGSMITH_WORKSPACE_ID`, `LANGSMITH_TENANT_ID` or the profile, highest first.
+
+What langstar takes from it: a file between a read run and a write run, a `:tag` or `--commit` to choose the commit, and output to stdout or a file.

openspec/changes/export-import-prompts-and-assistants/references/langsmith-go.md

@@ -0,0 +1,13 @@
+# LangSmith Go SDK
+
+Read at [langsmith-go 59bb42c3](https://github.com/langchain-ai/langsmith-go/tree/59bb42c30052067fe488f9bb8370df9037c715ef).
+
+[`CommitGetParams`](https://github.com/langchain-ai/langsmith-go/blob/59bb42c30052067fe488f9bb8370df9037c715ef/commit.go#L337) takes `include`, a comma-separated list of `model` and `is_draft`, and marks the boolean `include_model` deprecated.
+
+[`CommitGetResponse`](https://github.com/langchain-ai/langsmith-go/blob/59bb42c30052067fe488f9bb8370df9037c715ef/commit.go#L262) returns `commit_hash`, `description`, `examples`, `is_draft`, `manifest`, `model_config` and `model_provider`.
+
+[`CommitNewParams`](https://github.com/langchain-ai/langsmith-go/blob/59bb42c30052067fe488f9bb8370df9037c715ef/commit.go#L324) sends `manifest`, `parent_commit`, `description` and `skip_webhooks`. There is no field for the model outside the manifest.
+
+[`RepoNewParams`](https://github.com/langchain-ai/langsmith-go/blob/59bb42c30052067fe488f9bb8370df9037c715ef/repo.go#L310) requires `repo_handle` and `is_public` and takes `description`, `readme` and `tags`.
+
+What langstar takes from it: `include=model` on export, and the repo fields an export carries.

openspec/changes/export-import-prompts-and-assistants/references/langsmith-sdk.md

@@ -0,0 +1,13 @@
+# LangSmith Python SDK
+
+Read at [langsmith-sdk 47c553ca](https://github.com/langchain-ai/langsmith-sdk/tree/47c553caf08c1989e2be3ff1886da3eb801f709f).
+
+[`pull_prompt_commit`](https://github.com/langchain-ai/langsmith-sdk/blob/47c553caf08c1989e2be3ff1886da3eb801f709f/python/langsmith/client.py#L10107) adds `?include_model=true` when asked. The result, [`PromptCommit`](https://github.com/langchain-ai/langsmith-sdk/blob/47c553caf08c1989e2be3ff1886da3eb801f709f/python/langsmith/schemas.py#L1035), holds the manifest plus `model_config` and `model_provider`.
+
+With the model included, the manifest in the [integration fixture `prompt_with_model`](https://github.com/langchain-ai/langsmith-sdk/blob/47c553caf08c1989e2be3ff1886da3eb801f709f/python/tests/integration_tests/test_prompts.py#L48) is a constructor with the `id` `["langsmith", "playground", "PromptPlayground"]`, which LangChain loads as a `RunnableSequence`. Its `first` step is the `ChatPromptTemplate` or `StructuredPrompt` (with `schema_`), and its `last` step is a `RunnableBinding` around the chat model constructor and its settings.
+
+The chat model refers to its API key as a secret reference, `{"lc": 1, "type": "secret", "id": ["OPENAI_API_KEY"]}`. [`_manifest_has_secrets`](https://github.com/langchain-ai/langsmith-sdk/blob/47c553caf08c1989e2be3ff1886da3eb801f709f/python/langsmith/client.py#L434) finds these by matching objects whose keys are exactly `lc`, `type` and `id`. [`pull_prompt`](https://github.com/langchain-ai/langsmith-sdk/blob/47c553caf08c1989e2be3ff1886da3eb801f709f/python/langsmith/client.py#L10228) defaults `secrets_from_env` to `False`, and loading a manifest that holds a secret reference raises unless the caller passes a `secrets` map or sets `secrets_from_env=True`.
+
+[`create_commit`](https://github.com/langchain-ai/langsmith-sdk/blob/47c553caf08c1989e2be3ff1886da3eb801f709f/python/langsmith/client.py#L9915) resolves a missing parent to the latest commit, posts `{parent_commit, manifest, description}`, then posts each tag to `/repos/{owner}/{repo}/tags`. [`push_prompt`](https://github.com/langchain-ai/langsmith-sdk/blob/47c553caf08c1989e2be3ff1886da3eb801f709f/python/langsmith/client.py#L10309) creates the repo first when it does not exist.
+
+What langstar takes from it: the shape of a manifest with its model, how to find secret names, and the order of create repo, commit with parent, then tags.