@zoahhq/cli 0.1.7 → 0.1.9

package/README.md

@@ -41,8 +41,13 @@ Reads always check local first; falls back to global.
 zoah login                                      # global default
 zoah login --local                              # project-specific override
 zoah login --base-url https://zoah.example.com
+zoah login --organization acme                  # skip the organization list
 ```
 
+After you sign in, the CLI asks which organization to work in. Your active organization in the web app is first and selected. Use the arrow keys to choose another, then press Enter. An account with one organization skips the question.
+
+The CLI keeps this choice. Changing organizations in the web app does not change it. New projects from `zoah import` go into this organization, and so do directories that are imported but not swapped yet. A swapped directory stays on its project (see [Where a directory stands](#where-a-directory-stands)).
+
 The CLI uses `ZOAH_BASE_URL` when it is set. Otherwise, it uses `https://zoah.com`. `OPACITY_BASE_URL` remains a compatibility fallback.
 
 ### `zoah logout`
@@ -54,17 +59,37 @@ By default, this removes the **active** credentials. It removes project-local cr
 
 To clear both, run logout twice.
 
+### `zoah status`
+
+Prints who is signed in, the CLI's organization, and this directory's project, package and state, plus what the next `zoah import` will do. It reads local files only.
+
+```bash
+zoah status
+```
+
 ### `zoah whoami`
 
-Prints the active user, the source credentials file, and the base URL. Use this when project credentials hide the global token.
+Prints the active user, the source credentials file, the base URL, and the organization the CLI works in. Use this when project credentials hide the global token.
 
 ```bash
 zoah whoami
 # Signed in as you@example.com (global).
 #   Source:   ~/.zoah/credentials.json
 #   Base URL: https://zoah.com
+#   Organization: Acme (acme)
 ```
 
+### `zoah organization`
+
+```bash
+zoah organization list           # your organizations; * marks the CLI's
+zoah organization switch         # choose from the list with the arrow keys
+zoah organization switch acme    # or name one by slug, name or id
+zoah organization create "Acme"  # create one; switch to it to work there
+```
+
+`switch` changes the organization for the credential it came from, so a `--local` login keeps its own organization. The MCP server uses the same organization unless `connect` names another.
+
 ### `zoah mcp`
 
 Runs the Zoah MCP server over stdio so a coding agent (Claude Code, Codex,
@@ -198,18 +223,32 @@ zoah import                       # scans ./src
 zoah import src/components        # scope to a subdirectory
 zoah import --swap                # also rewrite local imports after publish
 zoah import --project-name my-ui  # override the first project name
+zoah import --new-project         # start over in a new project (before a swap)
 zoah import --branch main         # target a specific branch
 zoah import --debug               # also write .zoah/debug/payload.json
 zoah import --print-issues warn   # print issue details at or above this level
 zoah import --dry-run             # preview locally without an API call
 ```
 
-The first import creates a project and saves its IDs to `.zoah/config.json`. Later imports use the same project.
+The first import creates a project and saves its IDs to `.zoah/config.json`. Before it scans, `zoah import` says where the directory stands and where this import goes.
+
+#### Where a directory stands
+
+`zoah status` prints this without scanning or calling the API.
+
+| State    | What it means                                                 | What `zoah import` does                                                                                                                                                                                                       |
+| -------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| New      | No `.zoah/config.json`.                                       | Creates a project in the CLI's organization.                                                                                                                                                                                  |
+| Imported | Linked to a project, but no source file uses its package yet. | Updates the linked project. If the CLI's organization is different, it creates a project there and relinks the directory. `--new-project` also starts a new project.                                                          |
+| Swapped  | `zoah swap` rewrote component files to use the package.       | Adds and updates components in the linked project, whichever organization the CLI is in. Swapped components are already in Zoah, so the scan skips them. `--new-project` is refused, because the code depends on the package. |
+
+A swapped directory stays on its project because its code imports that project's package. It still takes new components: add one and run `zoah import --swap`.
 
 Notable flags:
 
 - `--swap`: runs `zoah swap` after a successful import.
-- `--project-name <name>`: sets the first project name. Later imports use the project ID in `.zoah/config.json`.
+- `--project-name <name>`: sets the name of a new project. Later imports use the project ID in `.zoah/config.json`.
+- `--new-project`: creates a new project in the CLI's organization and relinks the directory. Not possible once the directory is swapped.
 - `--branch <name>`: defaults to the project's saved branch (usually `main`).
 - `--base-url <url>`: overrides the URL saved at login.
 - `--print-issues <level>`: also prints full details for every issue at or above `info | warn | error`.
@@ -255,6 +294,14 @@ default, so the install needs credentials. When the repo's `.npmrc` (and your
 `~/.npmrc`) has no token for the Zoah registry host, swap mints a registry
 API key for the project's organization and manages the file for you:
 
+- A key reads only its own organization's packages. When `.npmrc` already has
+  a key, swap asks the registry whether that key can read this package. If the
+  registry refuses it (401 or 403), for example because the key came from a
+  project in another organization, swap replaces it with a key for this
+  project and says so. `.npmrc` holds one key per registry host, so a repo
+  that installs packages from two organizations needs a key that can read
+  both.
+
 - The key is requested through the authenticated import API, requires write
   access in the project's organization, and is **reused** on repeat runs (one
   key per project + user, not one per invocation). It appears in Project