@baldaworks/balda-linux-arm64 0.3.0 → 0.4.0

package/README.md

@@ -15,7 +15,7 @@ summary, changed files, validation output, a commit, or a concrete next step.
 
 ## What Balda is good for
 
-- chat-native engineering help in Telegram, Zulip, or Slack
+- chat-native engineering help in Telegram, Zulip, Slack Agent, or Mattermost DMs/channel threads
 - focused task threads instead of one shared bot conversation
 - long-running goal execution with progress updates and final results
 - `wedge` style operation: put the agent in the middle of your team workflow so
@@ -26,7 +26,7 @@ summary, changed files, validation output, a commit, or a concrete next step.
 
 You need:
 
-- one chat surface: Telegram, Zulip, or Slack
+- one chat surface: Telegram, Zulip, Slack, or Mattermost
 - one supported provider CLI installed on the host or in Docker:
   `codex`, `opencode`, `copilot`, `gemini`, or `claude`
 - Node.js/npm, unless you run the Docker Compose path
@@ -43,15 +43,42 @@ Initialize in your project:
 balda init
 ```
 
-Start:
+`balda init` also creates the Backoffice administrator with username `superuser` and prints its generated
+password once. Save it securely, then start:
 
 ```bash
 balda start
 ```
 
 `balda init` creates `.config/balda/config.yaml`, initializes
-`.config/balda/state.db`, detects available provider CLIs, and prints the next
-step for your selected chat provider.
+`.config/balda/state.db` by default, detects available provider CLIs, and prints
+the next step for your selected chat provider.
+
+SQLite is the default state database. To select PostgreSQL, configure
+`balda.database.type: postgres`; launch remains `balda start`.
+See [database configuration and operations](docs/reference/database.md).
+
+`balda start` applies embedded schema migrations to the selected database,
+checks canonical users and administrator bootstrap, then starts the bot,
+Backoffice, and enabled integrations in one process. Before the first start,
+the administrator is already bootstrapped on a fresh database. For an existing installation,
+stop Balda, back up the database, and convert legacy owner/collaborator records
+with an exclusive credentials-output file. See the
+[Backoffice startup and security contract](docs/reference/backoffice.md).
+
+```bash
+# Existing installation with legacy users, while Balda is stopped and after a database backup:
+balda backoffice migrate-users --credentials-output /run/secrets/balda-migrated-users.txt
+balda backoffice bootstrap-admin --reset
+balda start
+```
+
+The existing-install `--reset` step generates and prints a new password for the
+migrated primary user. It is needed when that user
+has a temporary credential; it revokes that user's browser refresh-token
+families. Never pass passwords or generated migration credentials as command
+arguments. Distribute the plaintext migration manifest out of band and
+securely remove it after verified delivery.
 
 ## First run
 
@@ -71,6 +98,8 @@ From there you can:
 
 - ask for ordinary help in chat
 - start a goal loop with `/goalkeeper <objective>`
+- run a session skill with `/skill <skill> [prompt...]` or
+  `/skill <plugin>:<skill> [prompt...]`
 - stop the current turn with `/cancel`
 - reset the current session with `/reset`
 
@@ -118,13 +147,21 @@ automation, and agent execution instead of separate bots and scripts.
 
 - Telegram
 - Zulip
-- Slack
+- Slack Agent DMs and mentioned channel threads
+- Mattermost DMs and mentioned channel threads
 
 Balda maps each conversation scope to its own session:
 
 - Telegram direct chat or personal/group topic
 - Zulip stream + topic
-- Slack thread
+- Slack Agent DM or mentioned channel thread
+- Mattermost DM, channel, or channel thread
+
+In Slack channels, every turn requires an explicit `@Balda` mention. A mention
+inside an existing thread can use its preceding accessible discussion and
+persisted files as bounded context; ordinary channel messages never activate
+Balda. With the optional `files:write` scope, generated photos and documents
+are delivered back into the same root thread from bounded local files.
 
 ## Docker Compose
 
@@ -141,7 +178,8 @@ docker compose up -d balda
 ```
 
 Polling mode is the default, so Telegram does not require publishing a port.
-Webhook deployment details live in [docs/balda.md](docs/balda.md).
+Webhook deployment details live in the
+[configuration reference](docs/reference/configuration.md).
 
 ## Published container image
 
@@ -178,16 +216,43 @@ ENTRYPOINT ["balda"]
 
 ## Core commands
 
-- `/start owner=<owner_token>` — owner bootstrap in direct messages
-- `/start invite=<invite_token>` — collaborator onboarding
-- `/topic <name>` — open a focused session
-- `/goalkeeper <objective>` — run a longer goal loop
-- `/goalkeeper clear` — stop active goal work in the current session
-- `/cancel` — stop the current turn
-- `/reset` or `/restart` — clear the current session and start fresh
-- `/locator` — show the current session locator for scheduler/webhook routing
+Balda provides onboarding, session control, GoalKeeper, locator, usage, skill,
+user, and plugin commands. Telegram and Zulip use `/skill`, `/locator`, and
+`/reset`; Slack exposes the conversation-scoped forms `/balda skill`,
+`/balda locator`, and `/balda reset`.
+
+Slack formats the response for scanning and copying:
+
+````text
+📍 *Balda Locator* • *Transport:* `slackagent` • *Locator:* `slackagent:c:T0BFTRBFA94:C0BU4LKUB6W`
 
-Full command behavior is documented in [docs/balda.md](docs/balda.md).
+*Scheduler / webhook configuration*
+```
+target: locator
+key: slackagent:c:T0BFTRBFA94:C0BU4LKUB6W
+```
+````
+
+See the [complete command reference](docs/commands.md) for syntax, transport
+availability, access, valid contexts, effects, errors, and examples.
+
+Owner plugin lifecycle commands include `install`, explicit origin adoption for
+migrated installs, `upgrade`, `enable`, `disable`, `rollback`, `remove`,
+explicit `purge`, and bounded `status`.
+Every chat command is durably published and executed by `CommandActor`;
+plugin-contributed commands are declarative, revision-pinned normal turns and
+never native plugin handlers.
+`/skill <skill> [prompt...]` selects one uniquely named skill from the current
+session snapshot. Use `/skill <plugin>:<skill> [prompt...]` to select an exact
+plugin source. The optional trailing prompt becomes the turn text; the skill
+body stays lazy until the turn executes. Balda discovers standalone skills from
+the runtime account's `$HOME/.agents/skills`, `$CODEX_HOME/skills` (defaulting
+to `$HOME/.codex/skills`), `<state_dir>/skills`, and the current workspace's
+`.agents/skills`; enabled plugins contribute their own skills. Run `/reset` to
+adopt skills installed or changed after the session was created.
+See [Plugins and session capabilities](docs/reference/plugins.md) for the
+`dev.baldaworks.balda` extension schema and the session-bound command, skill,
+and MCP lifecycle.
 
 ## Configuration
 
@@ -214,10 +279,18 @@ Common settings:
 
 - `balda.provider` — which configured provider runtime to use
 - `balda.telegram.token` — Telegram bot token
+
+Explicit `model` and `reasoning_effort` values on an ACP provider are reapplied
+to restored sessions after restart. Persisted values for settings omitted from
+the provider configuration remain unchanged, so changing an explicit setting
+does not require `/reset`. Custom ACP servers can set `model_config_id` and
+`reasoning_effort_config_id` when their advertised option IDs differ.
 - `balda.telegram.formatting_mode` — Telegram output mode: `rich_markdown`
   (default), `rich_html`, or `none` for literal plain text
 - `balda.zulip.*` — Zulip outgoing webhook bot credentials and receiver config
-- `balda.slack.*` — Slack bot token, signing secret, and HTTP receiver config
+- `balda.mattermost.*` — Mattermost bot credentials (`enabled`, `server_url`,
+  `token`, `bot_user_id`, `bot_username`) for websocket event ingress
+- `balda.slack.*` — Slack Agent credentials plus `agent.*` HTTP/streaming config
 - `balda.webhooks.*` — optional inbound webhook routes
 - `balda.scheduler.jobs` — recurring scheduled jobs
 - `balda.workspace.*` — workspace/worktree behavior for goal execution
@@ -272,8 +345,8 @@ ingress begins accepting messages. See the
 [Telegram formatting guide](docs/telegram-formatting.md) for rollout and
 fallback details.
 
-For complete configuration, examples, and provider-specific details, see
-[docs/balda.md](docs/balda.md).
+For complete configuration, examples, and provider-specific details, see the
+[configuration reference](docs/reference/configuration.md).
 
 ## Troubleshooting
 
@@ -290,11 +363,17 @@ For complete configuration, examples, and provider-specific details, see
 
 ## Docs
 
-- Product and operator docs: [docs/balda.md](docs/balda.md)
+- Technical reference: [docs/balda.md](docs/balda.md)
+- Onboarding: [docs/reference/onboarding.md](docs/reference/onboarding.md)
+- Configuration: [docs/reference/configuration.md](docs/reference/configuration.md)
+- Topic sessions: [docs/reference/topic-sessions.md](docs/reference/topic-sessions.md)
+- Session memory: [docs/reference/session-memory.md](docs/reference/session-memory.md)
+- Operations: [docs/reference/operations.md](docs/reference/operations.md)
 - Goal workflow: [docs/goal-workflow.md](docs/goal-workflow.md)
 - Architecture map: [docs/architecture/index.md](docs/architecture/index.md)
 - Telegram formatting: [docs/telegram-formatting.md](docs/telegram-formatting.md)
 - Zulip webhook setup: [docs/zulip-webhook.md](docs/zulip-webhook.md)
+- Mattermost setup: [docs/mattermost.md](docs/mattermost.md)
 - Slack setup: [docs/slack.md](docs/slack.md)
 - Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
 
@@ -304,5 +383,6 @@ For complete configuration, examples, and provider-specific details, see
 - npm package: <https://www.npmjs.com/package/@baldaworks/balda>
 
 npm releases are published from Git tags through the Omnidist workflow. The
-`NPM_PUBLISH_TOKEN` repository secret must have permission to publish the public
-`@baldaworks/balda` package in the `baldaworks` npm organization.
+workflow uses npm trusted publishing with GitHub Actions OIDC; it does not use a
+long-lived npm publish token. Each `@baldaworks/balda*` package trusts the
+`baldaworks/balda` repository and the `omnidist-release.yml` workflow.

package/bin/balda

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/bin/balda
-size: 49283234 bytes
-sha256: eba2cf6db50d29c8a2bc8ee5383e4386d2d8a16f993bea1b27cd4e2706c42246
+size: 57737378 bytes
+sha256: 5ecf2d299bc871e819e4c61c2c2d1ebcf2af11c9d0d0c846379c78a7848764f1

package/package.json

@@ -1,7 +1,4 @@
 {
-  "bin": {
-    "balda": "bin/balda"
-  },
   "cpu": [
     "arm64"
   ],
@@ -16,5 +13,9 @@
   "os": [
     "linux"
   ],
-  "version": "0.3.0"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baldaworks/balda.git"
+  },
+  "version": "0.4.0"
 }