@hasna/instructions 0.5.6 → 0.6.1

package/README.md

@@ -124,7 +124,8 @@ Surfaces:
 - `GET /openapi.json`, `GET /v1/openapi.json` → the OpenAPI 3.1 document the SDK
   is generated from.
 - `/v1/*` — versioned cloud API (configs, profiles, snapshots, stats).
-- `/api/*` — the local dashboard/REST surface.
+- No `/api/*` — the former local REST surface is not mounted (the removed
+  bundled dashboard was its only consumer).
 
 ### Server data backend (postgresql)
 
@@ -144,25 +145,72 @@ contracts issue-key --app instructions --scopes 'instructions:*'
 
 Env: `HASNA_INSTRUCTIONS_DATABASE_URL` (DSN) and
 `HASNA_INSTRUCTIONS_API_SIGNING_KEY` (HMAC signing secret; `HASNA_API_SIGNING_KEY`
-and `API_KEY_SIGNING_SECRET` are also accepted). Client apps use
-`INSTRUCTIONS_API_URL` + `INSTRUCTIONS_API_KEY` — never a DSN.
+and `API_KEY_SIGNING_SECRET` are also accepted). Client apps never carry a DSN —
+they resolve `HASNA_INSTRUCTIONS_API_KEY` (or the Keychain / credentials-file
+tiers) through the one `@hasna/contracts` client resolver, and the authority
+defaults to the fleet gateway `https://api.hasna.com/instructions`.
 
 ## SDK
 
-`@hasna/instructions-sdk` ships a zero-dependency typed client. The versioned
-`InstructionsV1Client` is generated from the serve OpenAPI document
-(`bun run generate:sdk`).
+The importable module ships INSIDE `@hasna/instructions` at the `./sdk` export
+(one package per app — there is no split `@hasna/instructions-sdk`). It is a
+self-contained bundle (node builtins only; the `@hasna/contracts` resolver is
+inlined at build time). The versioned `InstructionsV1Client` is generated from
+the serve OpenAPI document (`bun run generate:sdk` → `src/sdk/v1.generated.ts`).
 
-## Client transports
+```typescript
+import { createInstructionsV1ClientFromEnv } from "@hasna/instructions/sdk";
+
+const client = createInstructionsV1ClientFromEnv(); // Keychain -> disk -> HASNA_INSTRUCTIONS_API_KEY
+const { configs = [] } = await client.listConfigs({ category: "rules" });
+```
 
-Every CLI command, MCP tool, and SDK method routes through a single `ConfigStore`
-abstraction with two transports:
+`createInstructionsV1ClientFromEnv` resolves the credential through the same
+`@hasna/contracts` chain as the CLI and the MCP server — fresh on every
+request, so a rotated key heals a long-lived client without rebuilding it.
+`resolveInstructionsSdkTransport(options)` reports WHICH tier supplied the
+credential (never the value). An explicit `baseUrl` requires an explicit
+`apiKey` (hasna/apps#1794): the SDK never attaches the machine's fleet key to
+an authority the caller chose itself. No credential anywhere throws; there is
+no local mode and no unauthenticated client on this surface.
+
+## Client transports
 
-- **local** — on-box SQLite (`LocalConfigStore`), fully first-class. Used when no
-  API env vars are set.
-- **api** — HTTP `/v1` + bearer key (`CloudConfigStore`).
-  Activated by setting **both** `HASNA_INSTRUCTIONS_API_URL` and
-  `HASNA_INSTRUCTIONS_API_KEY`.
+Every CLI command, MCP tool, and SDK method resolves its credential and service
+authority through the ONE client resolver in `@hasna/contracts`
+(`hasna/apps#1720`) — the package owns no second chain. The tiers, fresh per
+call:
+
+| Tier | Credential | Authority |
+|---|---|---|
+| 1 — argument | `--api-key` / `--profile` | explicit `baseUrl` (SDK only) |
+| 2 — env pointer | `HASNA_INSTRUCTIONS_API_KEY_OVERRIDE`, `HASNA_PROFILE`, `HASNA_INSTRUCTIONS_API_KEY_REF` | — |
+| 3 — macOS Keychain | `hasna.credentials.instructions.api-key` (account `HASNA_STATION` → `hostname -s` → `$USER`) | `hasna.credentials.instructions.api-url` |
+| 4 — disk | `~/.hasna/instructions/config/credentials` (owner-only 0400/0600; `HASNA_HOME` / `HASNA_CONFIG_HOME` move the root) | same file's `HASNA_INSTRUCTIONS_API_URL` |
+| 5 — env | `HASNA_INSTRUCTIONS_API_KEY` | `HASNA_INSTRUCTIONS_API_URL` |
+
+With a credential resolved and nothing configuring the authority, the default is
+the fleet gateway `https://api.hasna.com/instructions`. The unprefixed
+`INSTRUCTIONS_API_URL` / `INSTRUCTIONS_API_KEY` names are accepted for one
+release as silent aliases one rung below the canonical `HASNA_INSTRUCTIONS_*`
+names.
+
+The two transports behind `ConfigStore`:
+
+- **api** — HTTP `/v1` through the shared authenticated transport
+  (`CloudConfigStore`). Runs fail loud with no credential: non-zero exit naming
+  the tiers consulted, no SQLite fallback, no local-fallback event.
+- **local** — on-box SQLite (`LocalConfigStore`), **opt-in only**:
+  `HASNA_INSTRUCTIONS_LOCAL=1`, honoured only when the environment configures
+  no authority and no credential. Every local run says `local mode` once on
+  stderr. The SQLite half is loaded through a single dynamic import and is
+  bundled as a separate chunk, so `dist/cli/index.js` and `dist/mcp/index.js`
+  ship with zero `bun:sqlite` references and a hosted run never loads it.
+
+Retired locations (`~/.hasna/fleet-env`, `~/.hasna/cloud`, `~/.config/hasna`,
+`$XDG_CONFIG_HOME`, a `~/.instructions/config.json` key store) are inputs
+nowhere, and no `*_MODE` / `*_STORAGE_MODE` switch selects anything — the
+transport is decided by what resolves, never by a mode word.
 
 Clients never hold a database DSN. The raw Postgres connection is a server-only
 concern (`instructions-serve`), selected by `HASNA_INSTRUCTIONS_DATABASE_URL`.
@@ -170,7 +218,7 @@ concern (`instructions-serve`), selected by `HASNA_INSTRUCTIONS_DATABASE_URL`.
 ## Data Directory
 
 Local data (the SQLite store and backups) lives under the configs store home,
-resolved through `@hasna/paths`. The legacy `~/.hasna/instructions/` default
+resolved by the in-package resolver. The legacy `~/.hasna/instructions/` default
 (with the `HASNA_CONFIGS_HOME` exact-app override) stays the effective store
 home until the store has actually been migrated to the XDG config home
 (`~/.config/hasna/configs` on Linux; `~/Library/Application
@@ -217,6 +265,28 @@ manifests for drift, refuses unmanaged file conflicts unless `--force` is
 passed, removes stale managed mirrors only when safe, and writes local snapshots
 before mutating managed files.
 
+Grok Build and Devin CLI can render global instructions into an explicitly
+selected native home. Pass Grok's `GROK_HOME` directory or Devin's resolved user
+config directory as `--target-home`; the renderer writes a flattened `AGENTS.md`
+and its ownership manifest there. Devin's target is the `devin` config directory,
+not its parent `XDG_CONFIG_HOME` or its credential-data directory.
+
+```bash
+instructions session plan --tool grok --profile work \
+  --target-home "$GROK_HOME" --identity-export ./instructions.json --json
+instructions session apply --tool devin --profile work \
+  --target-home /absolute/isolated/config/devin --identity-export ./instructions.json
+```
+
+An explicit `--project-root` keeps the project renderer: Grok writes repository
+`AGENTS.md`; Devin writes `.devin/rules/*.md`. Without either explicit target,
+these providers remain blocked. Compiled native profiles select the
+`native-profile` capability (Grok 1.0.13+, Devin 3000.10.21+); conditional bindings
+require an explicit supported fallback because global `AGENTS.md` is always on.
+The existing conflict, drift, symlink and snapshot checks also apply to native homes.
+See [Devin global rules](https://docs.devin.ai/cli/extensibility/rules) and
+[Grok settings](https://docs.x.ai/build/settings) for native home configuration.
+
 ### Session renderer ownership
 
 Anything the session renderer writes is off limits to `instructions apply` and
@@ -344,12 +414,9 @@ These profiles resolve machine variables like `{{WORKSPACE_ROOT}}`,
 `{{BUN_BIN_DIR}}`, `{{BUN_PATH}}`, and `{{PATH_PREFIX}}`, so synced configs can be
 portable across Linux and macOS arm64 machines.
 
-They also include project dashboard variables used by agent-managed project
+They also include the project channel variable used by agent-managed project
 workflows:
 
-- `{{PROJECT_DASHBOARD_DIR}}` -> `.hasna/project`
-- `{{PROJECT_DASHBOARD_RENDER_MANIFEST}}` -> `.hasna/project/dashboard/render.json`
-- `{{PROJECT_DASHBOARD_SNAPSHOTS_DIR}}` -> `.hasna/project/dashboard/snapshots`
 - `{{PROJECT_CHANNEL_PREFIX}}` -> `""` (no prefix; the channel is the normalized project slug)
 
 Existing profiles can be migrated in place without deleting or recreating them:
@@ -361,8 +428,9 @@ instructions profile update linux-arm64 \
 ```
 
 `instructions init` and `bun run seed` seed the
-`agent-managed-project-dashboard-standard` reference. It documents the standard
-`.hasna/project` layout, `projects dashboard *` commands, provider panel
+`agent-managed-project-dashboard-standard` reference. It documents the canonical
+per-workspace store layout (`~/.hasna/projects/workspaces/<workspace_id>/` — the
+only project-layout convention), `projects dashboard *` commands, provider panel
 commands, normalized project-slug channel naming, durable todos/goal workflow,
 and the rule that dashboards must show ids/statuses/evidence refs instead of raw
 private documents or secrets.

package/dist/chunks/apply-sfzja1f3.js

@@ -0,0 +1,22 @@
+// @bun
+import {
+  applyConfig,
+  applyConfigs,
+  applyConfigsWithReport,
+  expandPath,
+  getConfigHome,
+  normalizeTargetPath,
+  previewConfigs
+} from "./index-e9epbsvs.js";
+import"./index-1hpwskwd.js";
+import"./index-pkscjnj5.js";
+import"./index-bsan4c16.js";
+export {
+  previewConfigs,
+  normalizeTargetPath,
+  getConfigHome,
+  expandPath,
+  applyConfigsWithReport,
+  applyConfigs,
+  applyConfig
+};

package/dist/chunks/apply-ynfn1av7.js

@@ -0,0 +1,23 @@
+// @bun
+import {
+  applyConfig,
+  applyConfigs,
+  applyConfigsWithReport,
+  expandPath,
+  getConfigHome,
+  normalizeTargetPath,
+  previewConfigs
+} from "./index-axhwg61p.js";
+import"./index-v7dkb384.js";
+import"./index-35z65jsa.js";
+import"./index-pkscjnj5.js";
+import"./index-nnwp92tk.js";
+export {
+  previewConfigs,
+  normalizeTargetPath,
+  getConfigHome,
+  expandPath,
+  applyConfigsWithReport,
+  applyConfigs,
+  applyConfig
+};