@mnbny/woof 0.1.0 → 0.1.1

package/README.md

@@ -2,7 +2,7 @@
 <p align="center">Design tokens for your coding agent's instructions.</p>
 
 <p align="center">
-  <img width="240" height="240" alt="image" src="https://github.com/user-attachments/assets/d31f6463-f17d-4229-af75-f915adbcef7e" />
+  <img width="240" height="240" alt="image" src="https://github.com/user-attachments/assets/2a079bf2-b98b-42a3-aea2-156798055599" />
 </p>
 
 My prompts, conventions, skills, and scripts were everywhere: copied between repos, stashed in ignored folders, slowly drifting apart. Every new project started the same way. Dig up the last agent file, copy it, fix the few lines that differ. All of it Markdown, and Markdown doesn't compose.
@@ -83,7 +83,7 @@ Edits, sharing, and repo setup work the same way. Your agent proposes, and you a
 
 If you can commit to a repo, like `acme`, keep its woof configuration there, and Git shares it with your team. Client repos are another story. Your agent instructions don't always belong in someone else's codebase, but your coworkers on that client could still use them. So keep the configuration in your woof home instead, like `globex`, and share it as a file.
 
-Ask your agent to export it. woof packs `globex`, your shared tokens, and every file they use into one zip:
+Ask your agent to export it. woof packs the tokens and files `globex` needs into one zip:
 
 <img src=".github/assets/readme/export.jpg" alt="you: share my globex setup with sam. agent: runs woof export --project globex, saves ~/.woof/exports/globex.woof.zip, and says to send it to Sam.">
 
@@ -93,6 +93,8 @@ On Sam's side, anything new comes straight in. Anything that differs from what S
 
 Before it writes anything, woof saves a backup.
 
+For values Sam should supply, like staging credentials, ask your agent to mark the token private before you share it. Sam gets a placeholder to fill in.
+
 ## Getting started
 
 woof runs through npx, so there's nothing to install. You need Node.js 22.13+, 24, or 26+.
@@ -205,6 +207,20 @@ Set `$type` to `bash`, `node`, `tsx`, or `bun`, and `$exec` becomes the script.
 
 The script runs in the repo root, and its output becomes the value. `$exec` can also be a file, like `"<root>/scripts/checks.sh"`, or a list of scripts that run in order and stop at the first failure.
 
+### Private values
+
+You might keep `globex`'s staging accounts in woof. Ask your agent to mark that token private before you share it with Sam. It adds `$private` to the token:
+
+```json
+{
+  "$type": "prompt",
+  "$exec": "user1:pass user2:pass",
+  "$private": true
+}
+```
+
+You still get the real value locally. The export replaces it with `{{-woof:private-}}`. Sam can import the configuration and ask their agent to fill in their own value. Until then, woof warns whenever their agent uses the token.
+
 ### Projects
 
 A project changes tokens for one codebase. It holds only what's different, and everything else comes from your shared tokens. A project lives in one of two places.
@@ -335,6 +351,7 @@ And `acme`'s repo config:
 | `$exec` | A resource | Prompt text, script source, or a `<root>/` or `<repo>/` file. Scripts also take a list. |
 | `$description` | A resource | Optional text for search |
 | `$tags` | A resource | Optional list of strings for search |
+| `$private` | A resource | Optional boolean. `true` replaces the content with `{{-woof:private-}}` on export. |
 | `$projects` | Your shared file | Private projects by name: inline, or a `<root>/` path to the project's own file, like `initech` |
 | `$metadata` | A private project | Optional `$basePaths` and `$worktreePaths` |
 | `$basePaths` | `$metadata` | Paths that select the project, including everything below them |
@@ -350,6 +367,7 @@ And `acme`'s repo config:
 - Shared tokens must resolve without a project. They can't reference project-only tokens or `<repo>` files.
 - An override replaces the whole token, including its description and tags. A project can't replace a shared namespace with a token, or a token with a namespace.
 - A missing reference or a cycle fails before any script runs. A token that references itself is a cycle.
+- `{{-...-}}` is reserved for internal markers. Add and import remapping reject token addresses that produce this syntax, such as `-draft-`. Write `{{{{-woof:private-}}}}` to show the private marker literally.
 - A checkout holds one repo config: `woof.config.json`, `.agents/woof.config.json`, or `.claude/woof.config.json`. Two different files fail.
 - Every config file declares `"$schemaVersion": 2`. woof never upgrades a file on its own. When it asks for a migration, rerun the command with `--migrate`.
 
@@ -361,8 +379,8 @@ Your agent runs these as `npx @mnbny/woof <command>`. Add `--help` to any comman
 | --- | --- | --- |
 | `woof readme` | Prints this guide. Agents run it first. | — |
 | `woof get [query…]` | Prints a token's value when the query is its exact path. Otherwise, searches. | `--search` to always search, `--project <name>` |
-| `woof add [path]` | Adds a token | `--type`, `--content`, `--description`, `--tag`, and one of `--shared`, `--repo`, or `--project <name>` |
-| `woof edit [path]` | Changes a token's content, description, or tags | `--content`, `--description`, `--tag`, `--shared` or `--override`, `--project <name>` |
+| `woof add [path]` | Adds a token | `--type`, `--content`, `--description`, `--tag`, `--private`, and one of `--shared`, `--repo`, or `--project <name>` |
+| `woof edit [path]` | Changes a token's content, description, tags, or privacy | `--content`, `--description`, `--tag`, `--private` or `--no-private`, `--shared` or `--override`, `--project <name>` |
 | `woof init [location]` | Creates a repo config or a private project | `--repo`, or `--name <name>` with `--base-path` and `--worktree-path` |
 | `woof projects` | Shows which project the current directory selects, and lists private projects | — |
 | `woof explain [path]` | Traces how a token resolves, without running scripts | `--project <name>` |
@@ -377,6 +395,7 @@ Every command also takes `--agent` and `--migrate`. `woof --help` and `woof --ve
 - `--content` takes text, the path of an existing file, or `-` to read standard input.
 - `--tag`, `--base-path`, and `--worktree-path` repeat: `--tag git --tag commits`.
 - In `edit`, an empty `--description` or `--tag` removes it. `--shared` changes a shared token for every project, and `--override` overrides it in the selected project only.
+- `--private` on `add` or `edit` sets `$private: true`. `edit --no-private` removes the field. Other edits preserve the privacy setting. Disabling privacy alone on an already public definition makes no change.
 - A qualified address, such as `'$projects.globex.git.commit'`, selects a project the same way `--project globex` does. Quote it so the shell leaves `$projects` alone.
 
 #### Agent mode and exit status
@@ -387,6 +406,15 @@ Every command also takes `--agent` and `--migrate`. `woof --help` and `woof --ve
 - `get` prints the value exactly as resolved, so you can pipe it.
 - Exit status is `0` on success, `1` on a failure or a handoff, and `130` on a cancellation.
 
+#### Export and import
+
+- Export starts with the selected project's tokens and follows their references after applying overrides. It omits unrelated shared tokens, overridden defaults, and unused files. An empty project exports no shared tokens.
+- A shared token that depends on a project override, directly or through another token, exports as a project token. Independent shared dependencies stay shared.
+- For each exported token with `$private: true`, woof replaces `$exec` with `{{-woof:private-}}` and keeps the token's address, type, metadata, and privacy flag. Files and references used only by the omitted content stay out of the archive.
+- Privacy applies only to the marked token. An unmarked token can still export the same file. Local values and source files stay unchanged, and recovery backups retain private values.
+- Import warns about placeholders and continues. A differing value at the same address in the same layer needs conflict review. A new project token is added even if it overrides a shared token.
+- Each lookup that reaches a private placeholder names the token, asks for its value, and warns on stderr. Replacing the marker with `woof edit` stops the warning and preserves the privacy flag.
+
 ### Scripts
 
 A script token runs each time your agent gets it, and whatever it prints becomes the value.
@@ -409,6 +437,7 @@ A script token runs each time your agent gets it, and whatever it prints becomes
 
 - Scripts run in the selected project's checkout, the same root as `<repo>`. Without one, they run in the current repo root, or in the current directory outside a repo.
 - A list of scripts runs in order and stops at the first failure.
+- A private placeholder returns a request for the missing value without starting a runtime. If any entry in a script list is a placeholder, none of the list runs.
 - The first `tsx` or `bun` run may need the network.
 - If a script fails, the lookup fails. woof doesn't undo what a script already did, and there's no timeout.
 - Only `get` runs scripts. Searching, `explain`, and `validate` never do.
@@ -471,3 +500,12 @@ pnpm test
 ```
 
 Design notes for contributors and agents live in [`.agents/docs/`](.agents/docs/index.md).
+
+## ...and why "woof"?
+
+<table>
+  <tr>
+    <td>After this interaction, I refer to my agents as woof.</td>
+    <td><img width="256" height="182" alt="telegram-cloud-photo-size-1-4954272345791073203-m" src="https://github.com/user-attachments/assets/d390675f-cf99-4acc-bca8-95a2a6076432" /></td>
+  </tr>
+</table>

package/cli/templates/add-draft.md

@@ -2,13 +2,14 @@ woof needs more input to add a token: {{missing}}.
 
 Draft the token from the conversation:
 
-1. Work out what the user wants to keep. Write the content as standalone instructions that make sense without this conversation.
+1. Work out what the user wants to keep. Make the content usable without this conversation.
 2. Check for a similar token with woof get 'TERMS' --search --agent. If one exists, ask the user whether to add a new token or to change the existing token with woof edit 'PATH' --agent.
-3. Choose a path that fits the existing namespaces below. Each name in the path contains only ASCII letters, digits, underscores and hyphens.
+3. Choose a path that fits the existing namespaces below. Each name in the path contains only ASCII letters, digits, underscores and hyphens. Avoid paths such as -draft- whose references use the reserved {{-...-}} marker syntax.
 4. Choose the type: prompt for instructions or other text, or bash, node, tsx or bun for a script.
 5. Write a one-line description and a few tags, so that discovery can find the token.
 6. Choose one target below. Shared tokens are available in every project. A project token exists only in that project, and it overrides a shared token at the same path.
-7. Show the user the path, target, type, description, tags and content. Save only after the user approves.
+7. If the user wants the content omitted from exports, add --private to the command. The token will export with a placeholder. Local access still returns its value.
+8. Show the user the path, target, type, description, tags, privacy setting and content. Save only after the user approves.
 
 Existing namespaces:
 {{namespaces}}

package/cli/templates/add-result.md

@@ -5,6 +5,7 @@ Type: {{type}}
 Content: {{content}}
 Description: {{description}}
 Tags: {{tags}}
+Private: {{private}}
 Overrides a shared token: {{override}}
 
 Check the token with {{command}}.

package/cli/templates/edit-draft.md

@@ -6,6 +6,7 @@ Configuration: {{configuration}}
 Content: {{location}}
 Description: {{description}}
 Tags: {{tags}}
+Private: {{private}}
 
 Current content:
 {{content}}
@@ -16,7 +17,8 @@ Layers:
 1. Work out the change from the conversation.
 2. Show the user the current and the new version. Apply the change only after the user approves.
 3. Pass only the fields that change. Tags replace the current set. --description '' removes the description, and --tag '' removes all tags.
-4. Put new content between the WOOF lines, so that it goes to standard input. If the content is in a script file, edit that file directly. woof then changes only the description and tags. To change a shared script for this project only, first run the command with --override alone. woof copies the script into the project and reports the copy. Then edit the copy.
-5. If the command has LAYER, replace it with one flag from Layers.
+4. --private replaces the content with a placeholder on export. --no-private removes the privacy flag, so the content can export again. Use only one of these flags. Replacing a placeholder's content preserves the privacy setting unless --no-private is given.
+5. Put new content between the WOOF lines, so that it goes to standard input. If the content is in a script file, edit that file directly. woof can still change its description, tags and export privacy. To change a shared script for this project only, first run the command with --override alone. woof copies the script into the project and reports the copy. Then edit the copy.
+6. If the command has LAYER, replace it with one flag from Layers.
 
 {{command}}

package/cli/templates/export-result.md

@@ -3,4 +3,6 @@ Exported {{project}}.
 Archive: {{archive}}
 Files: {{files}}
 
+The archive contains the project's tokens and only their required dependencies after applying project overrides. Tokens marked private contain placeholders.
+
 Import it with woof import {{archiveArgument}} --agent.

package/cli/templates/import-decision.md

@@ -8,9 +8,11 @@ Import needs the user's decision for this item. No import files change until eve
 
 Set choices[next.id] to the choice that the user makes:
 
-- "take": use the archive's version. It replaces the local item.
+- "take": use the archive's version. Add it if missing, or replace the local item.
 - "keep": keep the local item and skip the archive's version.
 - {"action":"add","address":"..."}: import it at a new address or path, and keep the local item.
 - {"action":"reuse","address":"..."}: use an identical local item instead of importing it.
 
+For token renames or reuse, avoid addresses such as -draft- whose references use the reserved {{-...-}} marker syntax.
+
 Save the file and run woof import {{archive}} --decisions {{decisions}} --agent.

package/cli/templates/import-private.md

@@ -0,0 +1,6 @@
+Warning: This archive contains private placeholders for these tokens:
+{{tokens}}
+
+Their values were omitted during export. Import can continue. After import, ask the user for the missing values and replace the placeholders with woof edit.
+
+A placeholder that differs from a local value in the same layer needs normal conflict review. A shared token with the same name does not by itself cause a conflict with a new project token.

package/cli/templates/private-value.md

@@ -0,0 +1 @@
+Token "{{path}}" needs a value because its private content was omitted during export. Ask the user to provide it, then update the token with woof edit.

package/cli/templates/private-warning.md

@@ -0,0 +1 @@
+Warning: {{message}}