@hasna/instructions 0.4.36 → 0.4.39

package/README.md

@@ -126,10 +126,10 @@ Surfaces:
 - `/v1/*` — versioned cloud API (configs, profiles, snapshots, stats).
 - `/api/*` — the local dashboard/REST surface.
 
-### Cloud mode (self-hosted, Amendment A1 pure-remote)
+### Server data backend (postgresql)
 
 When `HASNA_INSTRUCTIONS_DATABASE_URL` is set the `/v1` API reads/writes the
-shared cloud Postgres **directly** (no local sync/cache in the service) and every
+shared Postgres **directly** (no local sync/cache in the service) and every
 `/v1` request is authenticated with a `@hasna/contracts` API key
 (`x-api-key` or `Authorization: Bearer`). Reads need `instructions:read`, writes
 need `instructions:write` (an `instructions:*` key satisfies both).
@@ -153,24 +153,25 @@ and `API_KEY_SIGNING_SECRET` are also accepted). Client apps use
 `InstructionsV1Client` is generated from the serve OpenAPI document
 (`bun run generate:sdk`).
 
-## Storage Modes
+## Client transports
 
 Every CLI command, MCP tool, and SDK method routes through a single `ConfigStore`
 abstraction with two transports:
 
 - **local** — on-box SQLite (`LocalConfigStore`), fully first-class. Used when no
   API env vars are set.
-- **api** (self_hosted / cloud) — HTTP `/v1` + bearer key (`CloudConfigStore`).
+- **api** — HTTP `/v1` + bearer key (`CloudConfigStore`).
   Activated by setting **both** `HASNA_INSTRUCTIONS_API_URL` and
-  `HASNA_INSTRUCTIONS_API_KEY`. Identical client code; only the URL/key differ,
-  and the self_hosted/cloud distinction is enforced server-side by tenancy.
+  `HASNA_INSTRUCTIONS_API_KEY`.
 
 Clients never hold a database DSN. The raw Postgres connection is a server-only
-concern (`instructions-serve`).
+concern (`instructions-serve`), selected by `HASNA_INSTRUCTIONS_DATABASE_URL`.
 
 ## Data Directory
 
-Local data is stored in `~/.hasna/configs/` (unchanged, for fleet continuity).
+Local data (the SQLite store and backups) lives under the canonical data root
+`~/.hasna/instructions/` by default. `HASNA_CONFIGS_HOME` remains a supported
+override of the root for legacy setups.
 
 ## Session Instruction Rendering
 

package/assets/skills/inbox/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: inbox
+description: Arm and verify the package-owned Conversations watcher for direct messages and subscribed channels.
+---
+
+# Inbox
+
+Use the maintained `@hasna/conversations` surfaces. There is no separate
+`inbox` executable to install or copy.
+
+## Prepare the subscriptions
+
+Subscribe the session identity to every channel that can change its work:
+
+```bash
+conversations channel subscribe <channel> --from <agent> --preview-chars 320
+```
+
+Read the subscriptions back before arming:
+
+```bash
+conversations channel subscriptions --from <agent> --json
+```
+
+The readback must contain the intended, non-empty channel set. Each row must
+carry a seeded `since_message_id`, so the first watch cycle starts from the
+subscription baseline instead of replaying history.
+
+## Arm the watcher
+
+First prove the hosted heartbeat path works:
+
+```bash
+conversations agents heartbeat --from <agent> --json
+```
+
+Only after that command succeeds, arm:
+
+```bash
+conversations watch --from <agent> --all --interval 60000 --full-content
+```
+
+`--all` watches direct messages plus every subscribed channel. Several
+comma-separated identities may be supplied to `--from`; reads are the union
+and the first identity is primary for writes.
+
+The watcher reports repeated poll failures as `DEGRADED` and announces
+`RECOVERED` after a successful poll. Treat those lines as visibility state,
+not as message content.
+
+## Manual fallback when hosted watch is degraded
+
+If the heartbeat command fails, do not claim the watcher is armed. Keep the
+subscription baseline and use bounded manual reads until the hosted path is
+healthy:
+
+```bash
+conversations digest <channel> --since <ISO8601> --json
+conversations digest --to <agent> --since <ISO8601> --json
+conversations blockers --from <agent> --json
+```
+
+Page every digest through `has_more` and `next_cursor`. Preserve the newest
+successfully read timestamp or cursor between coordination passes. A manual
+read is degraded service: say so explicitly, schedule the next bounded pass,
+and do not describe it as a live monitor.
+
+## Verify delivery, not just process lifetime
+
+Have a different agent send one uniquely labelled canary to a subscribed
+channel and one direct message. The watcher must surface both within one poll
+interval. A running process, successful subscription write, or quiet first
+poll alone does not prove delivery.
+
+After both canaries arrive, record the local runtime gate:
+
+```bash
+instructions managed-skills status --from <agent> --delivery-verified --json
+```
+
+`--delivery-verified` is an evidence assertion, not a probe. Use it only in the
+same acceptance pass that observed both canaries.
+
+`conversations watch` does not monitor Todos assignments. If the session also
+needs task-assignment awareness, keep that as a separate bounded Todos read;
+do not add another Conversations wrapper or executable.

package/dashboard/README.md

@@ -1,73 +1,37 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## React Compiler
-
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+# Instructions dashboard (legacy API client)
+
+This directory contains a React/Vite dashboard with pages for configs,
+profiles, apply/sync, snapshots, and machines. Its checked-in API client uses
+the former unauthenticated local `/api/*` routes at
+`http://localhost:3457`.
+
+Current `instructions-serve` exposes authenticated `/v1/*` and deliberately
+does not mount `/api/*`. As a result, this dashboard is not operational against
+the current server until its client, response shapes, and authentication are
+migrated to `/v1`. The server may still serve `dashboard/dist` as static files
+when a build is present; serving the assets does not restore the old API.
+
+## Source layout
+
+- `src/api.ts` — fixed-base legacy `/api` client.
+- `src/pages/ConfigsPage.tsx` — search, inspect, and edit config content.
+- `src/pages/ProfilesPage.tsx` — create, inspect, preview, and apply profiles.
+- `src/pages/ApplyPage.tsx` — preview/apply configs and legacy directory sync.
+- `src/pages/HistoryPage.tsx` — inspect config snapshots.
+- `src/pages/MachinesPage.tsx` — machine and category statistics.
+
+## Development
+
+```bash
+bun install
+bun run dev
+bun run lint
+bun run build
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
+The Vite dev server alone does not provide API endpoints. For UI work before
+the `/v1` migration, use a purpose-built mock or a compatible legacy server;
+do not expose an unauthenticated `/api` shim in production.
 
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```
+See the repository's [HTTP API reference](../docs/http-api.md) for the current
+server contract.