@jungjaehoon/mama-os 0.78.0 → 0.79.1

package/CHANGELOG.md

@@ -7,6 +7,347 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.79.1] - 2026-11-01
+
+### Fixed
+
+- Enabling a source no longer asks again for a token `auth.env` already holds, so it cannot
+  switch a messenger to another bot (#552). The Slack and Discord sources read the same token as
+  the Slack and Discord messengers (`MAMA_SLACK_TOKEN`, `MAMA_DISCORD_TOKEN`). Before, enabling
+  the source, even to add a channel, asked for that token on the setup page, and a token entered
+  there became the messenger's at the next start. Now
+  `mama init --section connectors --non-interactive` keeps a stored token and prints that it did;
+  a blank value counts as missing, as it does for boot and `mama doctor`, and is asked for. It
+  asks for a stored token again only when `MAMA_INIT_REPLACE_SECRETS` names it, on a field that
+  says which messenger that is on also reads it, and refuses a name that no source being enabled
+  reads, before it looks for the sources' tools. At a terminal, `--section connectors`,
+  `--section slack` and `--section discord` ask before replacing a stored token, naming the
+  sources and messengers that are on and also read it; Enter keeps it. `--section connectors` no
+  longer asks for the Slack app token, which only the messenger reads. For a source whose stored
+  token is refused, `mama doctor` names `MAMA_INIT_REPLACE_SECRETS`.
+- `mama uninstall --data` removes the MAMA home entry by entry, goes on past one it cannot
+  remove, and names each one. Before, on Node 22 (the Node the install command installs), the
+  first failure stopped the removal, so later entries stayed, credentials among them, and only
+  that failure was reported (#540).
+- When anything before the MAMA home cannot be removed (a person's folder or temporary files, a
+  retired folder, the common skills or a toolkit version), `mama uninstall --data` keeps the MAMA
+  home and the program, names what could not be removed, and ends with the command to run again
+  once it is cleared, with `--toolkit` when it was given. That rerun finds what is left through
+  the kept config and database, a person's temporary files included after `member_root` went.
+  Before, the home went with the config and database that name those folders, so the rerun did
+  not find them and their data stayed with nothing pointing to it (#541).
+
+## [0.79.0] - 2026-11-01
+
+### Added
+
+- `google.read`: the owner agent reads Gmail, Calendar and Sheets, and a Google Doc, Sheet or
+  Slides file as text, live through `gws`, which the daemon runs with its own sign-in. The agent
+  names the method as gws takes it (`service`, `argv`, `params`); read methods only, and no gws
+  flag is an input, so nothing is sent or uploaded. Each call runs in a directory of its own that
+  is removed after it, and a response gws writes to a file instead of printing (a parameter such
+  as `alt` or `callback` asking for another format) is refused, never left on disk. A list
+  returns one page with its `nextPageToken`; a result over 100,000 characters is refused with how
+  to narrow it. A replay turn cannot use it: Google read now is past the replay's window. A missing `gws`, no sign-in, a sign-in without the service, an API not enabled in
+  the client's Cloud project, and a rate or quota refusal each come back saying what to do. The
+  result is quoted as external evidence and each call is in `tool_traces`. The common session has
+  it in chat, source changes and reports, and an owner-role person in their own DM; members
+  without the role and room sessions do not. Drive files are still found with `drive.read` and
+  fetched with `drive.download`.
+- Closing summaries for finished work. Every hour MAMA orders the work it saw closed or cancelled
+  since its first start with this version, ten items at a time. For each, the agent writes one
+  summary: the rounds, the points of outside feedback, who did what, and how it ended. Then a
+  later question reads one place. The order is checked item by item: a revision from the order's
+  run that leaves a description counts, as does a `work.no_update` naming an item whose summary
+  is already current. A status-only revision does not count. An item that
+  stays unchecked is ordered again, and after three orders it is logged as lost. `work.no_update`
+  can now name work items (`commitmentIds`) as well as observations.
+- A daily board check. Once a day, before the first full report, MAMA orders work items to
+  compare with the board: up to ten open items whose Trello card moved after the item was last
+  revised, and up to ten items in progress or in review with no source event in over 30 days,
+  oldest first. The agent reads each card live and either revises the item with the reason or
+  says why it stays. Each item is checked like the closing summaries. An item that was kept, or
+  given up on after three tries, comes back only after it is revised again. The stale-work step
+  leaves the daily page, since this order now does it.
+- Telegram commands MAMA answers itself, without a model turn, listed in the bot's command menu:
+  `/whoami` (your Telegram ID and whether MAMA knows you as an owner or a member), `/status`
+  (MAMA's version, whether a turn is running in this conversation, what waits; owners, in their
+  own DM, also see every conversation and the sources), `/new` (starts the conversation over;
+  refused while MAMA still works on something of that person's or a message of theirs waits) and
+  `/help`. In the common group an owner's commands act on the common session and a member's on
+  their own group conversation. Unregistered senders still get no answer, a command addressed to
+  another bot is left alone, and any other command goes to MAMA as a message.
+- `mama init` sets up a new install and starts it:
+  - **Checks first, before writing anything:** the backend is installed, at least the verified
+    version, and signed in; Telegram accepts the bot token; the member and tool folders stay
+    outside HOME. Those folders default to a folder of the user's (`Shared/mama-<user>/…` in the Shared folder beside the home folders
+    on macOS, `/var/lib/mama/<user>/…` on Linux), and init refuses one another account owns or can
+    write.
+  - **Sign-in:** init signs nothing in. A backend that is not signed in stops it before anything
+    is written, and init names the login with the backend's full path (`claude auth login`, or
+    `codex login` in MAMA's Codex home, which init creates), for the person's agent to run.
+    `mama init --section model` runs that login on its terminal, and offers the only backend on
+    PATH as the default answer (#539).
+  - **Then in order:** writes the setup, registers the person running it as the first owner,
+    installs the document tools, installs and starts the service through `mama service`, and
+    waits until the daemon reports it is running and the viewer answers `/health`. Last, the
+    daemon runs one real backend turn in a session of its own, so the login is proven as the
+    service runs it; a failure names `mama logs` and `mama doctor`, and the install command run
+    again checks it after a fix.
+  - **Repeat-safe:** a failed run continues from its last finished step.
+    On a finished setup, init says so, names `mama doctor`, `mama service restart` and
+    `mama update`, and exits 0 (#538, #539).
+  - **No typed Telegram IDs:** last, the bot sends a six-digit code to whoever messages it
+    privately, and the code entered on the setup page names the first owner; that owner's
+    `/bind` in a group names the common channel. Messages the bot held from before are dropped, a
+    bot another program already reads is refused, and no `/bind` within 15 minutes stops setup
+    with the way to continue.
+  - **One part again:** `mama init --section <part>` asks one part of a finished setup again
+    (`telegram`, `model`, `timezone`, `connectors`, `discord`, `slack`, `jev`) while MAMA is
+    stopped. The answers get init's checks, the result must pass the checks MAMA runs at boot
+    (delivery routes included) before anything is written, tokens go only to `auth.env`, and the
+    other parts stay as they were. A new bot must already be in the common group.
+  - **Without a terminal:** `mama init --non-interactive` reads `MAMA_INIT_*` variables, and takes
+    the bot token and the pairing code on its setup page.
+  - **No longer offered:** the Kagemusha bridge, which a fresh install cannot use, and the
+    launch-agent question, since the service is installed for you.
+- `/stop` in Telegram stops the turn running in that conversation and keeps the conversation: the
+  message it was answering is told it was interrupted and is not run again, and messages sent
+  after it still run. In the common group an owner stops the common session's turn and a member
+  their own.
+- A daily release check. Once a day the daemon asks npm for the latest MAMA OS release and keeps
+  the answer. `mama status` and `mama doctor` show it without a network call of their own: a newer
+  release and how this install updates (`mama update`, or the git commands for a checkout), that
+  this version is current, or when the last check failed (#534).
+- `mama update` updates an npm install to the latest release, or to the version you name:
+  - **Nothing changes first:** it asks the registry npm uses and shows the plan (`--dry-run`
+    stops there). It installs the new version next to the old one, so a failed download changes
+    nothing. A version older than the running one is refused (#535), and so is a release whose
+    Node.js range (`engines`) leaves out the Node that MAMA runs on (#539).
+  - **Then the swap:** it lets running turns finish as `mama stop` does, stops MAMA, takes a
+    backup with credentials and swaps the two versions. The new version writes `start.sh` and the
+    service file, checks the install, and starts with new work held. Once it runs and its viewer
+    answers, the held work runs, and the backup and the old version are removed (#535).
+  - **A failed step puts the old version back** with its own `start.sh` and service file, and
+    starts it. A check that newly fails under the new version counts as a failed step. The
+    database comes back from the backup only when the new version changed its schema, and the
+    report says how many inputs that arrived after the backup were dropped (#535).
+  - **Cut off:** if `mama update` itself is killed, `mama doctor`, and `mama status` on a stopped
+    install, name the `mama update --rollback` command that resolves it. `mama restore` refuses
+    until then (#535).
+  - **A git checkout** gets the commands that update it instead: stop, `git pull`,
+    `pnpm install`, `pnpm build`, `service install` and `service start` (#535).
+  - **The first update** needs a `start.sh` that this version's `mama service install` wrote, and
+    says so otherwise (#535).
+  - On an install the install command made, the report ends by naming the install command when
+    the new release pins another Node.js (#539).
+- `/update` in Telegram updates MAMA. Only an owner can run it, in their own DM or in the common
+  group. It runs `mama update` as a job of its own, with no model turn, so it works even when the
+  backend does not. Progress comes back to the same chat: versions, steps and error codes, never a
+  path. While an update runs, another `/update` says only since when. A git checkout answers with
+  the commands that update it; asked in the group, those go to the owner's DM, since they name
+  folders on MAMA's machine. `/update` is in the bot's command menu (#536).
+- An install command, `install.sh`, attached to each MAMA OS release starting with this one
+  (#538):
+  - It runs on macOS and Linux, on x64 or arm64, and reads no terminal. A new install is given
+    its backend (Claude Code or Codex) with `--backend`, and `--non-interactive` or `--no-init`.
+  - It puts Node.js in `~/.mama/node`, at a version it pins and checks by hash, MAMA OS in
+    `~/.mama/npm`, and a `mama` command in `~/.mama/bin`. The backend is installed with its
+    vendor's installer when none that runs is on PATH.
+  - It adds `~/.mama/bin` to PATH in a marked block of your shell's startup file (for fish it
+    prints the line instead), then runs `mama init --non-interactive`.
+  - On Linux it shows one `sudo` command and runs it: MAMA's folders under `/var/lib/mama`, and
+    linger, so the service keeps running after you log out. If sudo is refused, it prints the
+    command and goes on.
+  - Run again, it skips what is already in place. It will not take over a MAMA home that another
+    install set up.
+  - When a release pins another Node.js, running it again moves MAMA to that Node with
+    `mama update --node` (#539). That lets running turns finish, stops MAMA, swaps the Node in and
+    checks that MAMA starts on it. A new major version first rebuilds the installed packages for
+    that Node, before anything stops. If a step fails, the old Node is put back and started. If
+    the move is cut off, the next run of the install command finishes or undoes it, and
+    `mama status` and `mama doctor` say so.
+  - `mama doctor` warns when such an install runs another Node.js than its release pins (#539).
+- How to get `gws` when a Google source needs it (Calendar, Gmail, Drive, Sheets). `mama init`,
+  `mama init --section connectors` and `mama doctor` look for it where MAMA's service runs it: on
+  start.sh's PATH, or, before `mama init` has written start.sh, on the PATH it will write, which
+  carries the folder where the terminal finds `gws`. When the service would not find it, they
+  print how to install it and how to sign in. On an install the install command made, both
+  commands use MAMA's own Node and put `gws` where the service finds it:
+  `PATH="$HOME/.mama/node/bin:$PATH" ~/.mama/node/bin/npm install -g --prefix ~/.mama/npm @googleworkspace/cli`,
+  then `PATH="$HOME/.mama/node/bin:$PATH" ~/.mama/npm/bin/gws auth login --scopes <scopes>`.
+  Other installs get `npm install -g @googleworkspace/cli` or `brew install googleworkspace-cli`,
+  then `gws auth login --scopes <scopes>`. The login names the OAuth scope of every Google source
+  that is on (see Changed), since one login serves them all. Before it, `mama init` and
+  `--section` name the OAuth client gws signs in through: a Desktop app client from Google Cloud
+  Console, saved as `~/.config/gws/client_secret.json`. When only the terminal finds `gws`, they
+  say that `mama service install` adds its folder. MAMA's service does not start while such a
+  source is on and `gws` is missing, and they say so: `mama init`, continuing a setup that
+  stopped, names `gws` again and says to install it now and run the install command again, and
+  `--section` no longer enables the source (below). Doctor's fix for a source that does not
+  start, or whose sign-in is refused, names the same login command, and the sources' own errors
+  point to `mama doctor` for those commands instead of a bare `gws auth login` (#543).
+- `mama init --section connectors --non-interactive` enables sources without a terminal, for the
+  person's agent, while MAMA is stopped:
+  - It reads `MAMA_INIT_CONNECTORS`, a JSON object of `connectors.json` blocks keyed by source
+    name, checked as boot checks `connectors.json`. A source name or setting MAMA does not read is
+    refused.
+  - The tokens the sources read, as each source names them (Trello's key too), are entered on the
+    setup page, one field each, and go only to `auth.env`.
+  - The other parts of `mama init --section` still need a terminal.
+- A source is enabled only once its tool is installed where MAMA's service finds it and signed
+  in, from either form of `mama init --section connectors`. With a Google source and `gws`
+  missing from start.sh's PATH, boot stopped; signed out, every poll failed. The section saves
+  nothing and prints how to install `gws`, or the OAuth client file and the login
+  (`gws auth login --scopes <scopes>`, naming the OAuth scope of every Google source that is on,
+  since one login serves them all), then "Then run this again." The sign-in is each source's own check, run in the
+  environment start.sh gives the daemon: one read with that source's own scope (Gmail its
+  profile, Drive `about`, Sheets its first spreadsheet, Calendar the calendar), so a sign-in made
+  for other services is refused too, with gws's reason.
+- Each refusal of `mama init --section`, an expired setup page included, ends by saying MAMA is
+  still stopped and how to start it (`mama service install` first while no service is
+  installed). On an install the install command made, the section's lines
+  name `~/.mama/bin/mama`.
+- An enabled source already in `connectors.json` that boot cannot build refuses the section, which
+  names it and says how to turn it off: its block with `"enabled": false` in
+  `MAMA_INIT_CONNECTORS`.
+- `mama init --non-interactive` opens a setup page on this machine for the bot token and the
+  pairing code, once every other answer has been checked:
+  - The page listens on 127.0.0.1 at a path of 32 random bytes, and answers only a request whose
+    one Host header names `localhost`, `127.0.0.1` or `[::1]`, on any port. The address goes
+    only into `open.html`, a 0600 file in a 0700 folder, which init opens with `open` or `xdg-open`;
+    the address is never printed or passed as an argument, and the folder goes with the page. If
+    no browser opens, init prints the file's `file://` path.
+  - It takes the token, checked with Telegram, then the code the bot sent, by form POST. A refused
+    token or a wrong code is shown with its form again. After one token and one code it closes.
+  - Unused, it closes after 15 minutes, and setup stops without writing the setup; only the two
+    folders it made before the page opened stay. Neither the token nor the address appears in a
+    printed line or on the page.
+
+### Changed
+
+- The Google login MAMA prints (setup, `init --section connectors`, `mama doctor`) asks for
+  explicit scopes, `gws auth login --scopes <scopes>`: read-only for Gmail, Calendar and Sheets,
+  and full Drive access, which `deliver.drive.file` needs to upload into the owner's folder and
+  set its readers. It was `-s <services>`, which in a terminal opened gws's scope picker and
+  otherwise asked for gws's defaults (`gmail.modify`, full Calendar and Sheets). An existing
+  sign-in keeps working; signing in again with the printed line narrows it.
+- A closing summary, once checked, is not ordered again even if a later write clears or replaces
+  it. Before, an order was placed again when that happened within a week.
+- `mama stop` lets running work finish first. MAMA claims nothing new: messages, source changes
+  and reports that arrive wait for the next start, and Telegram commands such as `/stop` still
+  answer. The stop waits until running turns finish and their replies are delivered, and prints
+  what it waits for. It gives up after one `agent.max_turn_ms` for each turn that may still run,
+  plus a minute, or when the daemon stops answering; then nothing changes and it exits 1.
+  `mama stop --now` stops at once, as before. `mama service stop`, `mama service restart`,
+  `mama uninstall` and, on macOS, `mama service uninstall` stop the same way, and `mama status`
+  shows while a stop holds new work. A daemon older than this version refuses to drain, and
+  `mama stop` then names `--now` (#533).
+- `mama backup --restart` stops a running install the same way, backs it up and starts it again
+  through its service, also when the backup fails. Without an installed service it refuses before
+  it stops anything (#533).
+- `mama status` shows the Node.js version the daemon runs (#539).
+- `mama uninstall --data` also removes the program the install command put in the MAMA home
+  (Node.js, MAMA OS and the `mama` command), after everything else. Without `--data` it names that
+  program as staying. Both name the startup files that hold the install command's PATH block, for
+  you to remove. `mama backup` no longer lists that program as left out, since the install command
+  makes it again (#539).
+- `mama service install`, for an npm install, also puts the npm prefix's `bin` folder on
+  `start.sh`'s PATH, where npm puts commands installed beside MAMA (#539).
+- The install script asks nothing and runs from an agent's shell. A found backend must run before
+  the installer is skipped: its `--version` must exit 0 and print a version, so a shim with no
+  backend behind it gets the vendor's installer. A set-up install needs no flags: it runs
+  `mama init --non-interactive`, and without `--backend` it keeps the backend it has.
+- Slack, Chatwork and Trello sources read only `MAMA_SLACK_TOKEN`, `MAMA_CHATWORK_TOKEN` and
+  `MAMA_TRELLO_TOKEN`, so the setup page never takes another secret, such as the owner bot's
+  token or `MAMA_AUTH_TOKEN`. A block without `auth.tokenName` reads that name. A Slack or
+  Chatwork block without one read `SLACK_BOT_TOKEN` or `CHATWORK_API_TOKEN` before; it now needs
+  `MAMA_SLACK_TOKEN` or `MAMA_CHATWORK_TOKEN` in `auth.env`, and doctor names the one missing. A
+  block that names any other variable stops boot until it is corrected, and doctor names it.
+- `mama doctor`'s fix for a source token that is missing or refused names
+  `mama init --section connectors --non-interactive` with that source's block, whose setup page
+  takes the token, instead of `mama secret set`, which needs a terminal. A messenger's token
+  still names `mama secret set`.
+- The package README and the install guide (`docs/start/owner-setup.md`) describe setup through
+  the person's agent: the sentence to give it, naming this repository, and the install command it
+  runs, with `npm install -g` for a person who keeps their own Node.js. The guide lists the
+  supported versions of Node.js, Claude Code, Codex and macOS with their sources, what the install
+  command makes, how a new Node.js release is moved to, and the known limits: no setup path yet for
+  Linux over SSH or without a desktop, and the document tools on a Mac account without its own
+  Homebrew.
+
+### Removed
+
+- The interactive whole setup: bare `mama init` is now a usage error. `mama init --non-interactive`
+  is the setup, run by the person's agent ("Set up through your agent" in
+  `docs/start/owner-setup.md`), and its messages say to run the install command again. The tunnel
+  settings are read from the environment: `MAMA_CF_ACCESS_ISSUER`, `MAMA_CF_ACCESS_AUD` and
+  `MAMA_VIEWER_HOSTNAMES` together, and optionally `MAMA_VIEWER_OWNER_EMAILS`. Sources, Discord,
+  Slack and Jev are set up with `mama init --section`.
+- The init variables `MAMA_INIT_OWNER_TELEGRAM_ID` and `MAMA_INIT_COMMON_CHAT_ID`, and
+  `MAMA_TELEGRAM_TOKEN` as an init variable (the secret name stays): the setup page takes the token,
+  and the bot's pairing code and `/bind` name the owner and the common group.
+- The package no longer installs Express. Its only use was an old report router with write routes
+  that nothing ever served.
+
+### Fixed
+
+- A Notion, Discord or Telegram source whose block names another token than its own is refused
+  when the source is built, in the section, doctor and boot; before, only its start in boot
+  refused it.
+- Gmail, Drive and Sheets' sign-in check is a read with the source's own scope. It ran
+  `gws auth status`, which exits 0 signed in or not and does not say which services a sign-in
+  grants, so doctor reported a signed-out source, or one without its scope, as signed in.
+- Calendar starts as the other Google sources do, when `gws` runs. Its calendar read is its sign-in
+  check, so a sign-in that ended (a testing-mode client's, after 7 days) fails its polls and
+  doctor's check instead of stopping MAMA at boot.
+- A backend failure such as a signed-out Claude CLI or an API error no longer arrives as MAMA's
+  answer. The turn fails, its message is told it was interrupted, and `daemon.log` names the
+  error. Before, the CLI's error text was sent as the reply and the run was recorded as committed
+  (mama-core).
+- A scheduled full report or reminder that a newer report already covered is no longer sent.
+  Before, a report whose first send failed stayed queued and kept being retried, so it could still
+  go out days late; one had waited 13 days. Reports already stuck this way close after the next
+  full report is sent (#542).
+- After a report's send fails, MAMA no longer writes the same hour's report again every minute
+  (#542).
+- If the clock is behind the latest report sent, MAMA queues no report and logs an error each
+  minute naming that report's time, until the clock passes it (#542).
+- `mama stop` no longer refuses a MAMA that is just starting. In its first moments MAMA holds the
+  install before it can answer the stop or say which process it is. The stop used to report
+  "does not answer on its control socket" and leave it running, or report "unknown (pid 0) holds
+  the install" as still running after it had already stopped it (macOS). It now waits up to 5
+  seconds for MAMA to answer, then lets it finish what runs and stops it as usual. `mama stop
+--now` waits the same way, only while the holder is still unnamed, before it stops the service.
+  Running the install command again right after a Node move was cut off hit this: the install
+  command stopped with "MAMA on it did not stop" and changed nothing (#546).
+
+### Security
+
+- gws's credential store is now closed to the agents' own file reads and shell, as MAMA's own
+  credentials are (owner, 2026-10-31): its config directory (`~/.config/gws`, the legacy
+  `~/Library/Application Support/gws`, or the one `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` names) and a
+  `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`. MAMA's Google sources and `google.read` run on that
+  sign-in, and an agent that could read it, or run `gws auth export` against it, could carry the
+  refresh token, with Drive write access, out in a reply or a fetched URL. Claude's Read rules
+  and shell sandbox and the Codex permission profile all deny it; the daemon's own gws calls are
+  unaffected. Other tools' credential stores stay as they were.
+- Another website open in your browser can no longer read through MAMA's viewer in your name.
+  Before, a link or a page your browser had allowed onto this machine could make one viewer
+  request, such as a memory search with words it chose. MAMA ran that search as yours and kept
+  the words in its record of your actions. The viewer now answers such a request with 403 and runs
+  nothing. It records the request in `security-events.jsonl` as `cross_origin` and alerts you as
+  for other viewer security events. A page on another port of this machine counts as another
+  website. The viewer itself, a link or bookmark that opens it, curl and local tools work as
+  before. Through the tunnel, a bookmark to an `/api` address opened after your Cloudflare Access
+  sign-in expired comes back from the sign-in page as another website's request and gets 403;
+  open the viewer instead.
+- The board's live updates allow 8 open connections at once. Another connection is refused with
+  503 and a line in `daemon.log`, instead of each one adding memory without limit. The browser
+  does not retry a refused connection: that board keeps its content and its refresh button but
+  shows no live updates until the page is reloaded. A connection whose browser left while MAMA
+  was still checking its Cloudflare Access sign-in is no longer kept open for good.
+
 ## [0.78.0] - 2026-10-16
 
 ### Fixed

package/README.md

@@ -5,36 +5,50 @@ Codex, watch connected work, keep task revisions and evidence, answer in Telegra
 and the common group), Discord or Slack, publish reports and a board, and recall corrections.
 [mama-core](../mama-core/README.md) supplies the shared engine.
 
-Current manifest: **0.78.0**. Install with `npm install -g @jungjaehoon/mama-os` (Node.js 22.13+)
-and follow [owner setup](../../docs/start/owner-setup.md).
+Current manifest: **0.79.1**. Install it through your agent: on the Mac that will run MAMA, tell
+Claude Code or Codex "Install MAMA OS from https://github.com/jungjaehoon-lifegamez/MAMA by
+following its owner setup guide, docs/start/owner-setup.md". See
+[owner setup](../../docs/start/owner-setup.md), with the supported versions.
 
 ## Start and operate
 
+The agent runs the install command. It installs MAMA's own Node.js, MAMA OS and, when needed, the
+backend, then sets MAMA up and starts it:
+
+```bash
+curl -fsSL https://github.com/jungjaehoon-lifegamez/MAMA/releases/latest/download/install.sh | MAMA_INIT_MODEL=<model> sh -s -- --backend <claude|codex> --non-interactive
+```
+
+With your own Node.js 22.13 or newer, install with npm instead, then run setup:
+
 ```bash
 npm install -g @jungjaehoon/mama-os
-mama init
+MAMA_INIT_BACKEND=<claude|codex> MAMA_INIT_MODEL=<model> mama init --non-interactive
 ```
 
 From a checkout, run `pnpm install` and `pnpm build`, then use
-`node packages/standalone/dist/cli/index.js` in place of `mama`. Onboarding is terminal-only: the owner types tokens
-with echo off. It writes configuration and optional launchd files; backend login and service
-startup are separate steps.
-
-For Telegram's common session, create a group with the bot, even for a solo owner, and enter
-its negative group or supergroup ID in `mama init`. Private chats always enter personal sessions.
-Before starting the daemon, set `member_root` outside HOME in `config.yaml` and run
-`mama register-owner <telegram id>` for each owner's positive user ID.
-
-| Command                                       | Purpose                                          |
-| --------------------------------------------- | ------------------------------------------------ |
-| `mama init`                                   | Set up the owner, backend and connectors         |
-| `mama register-owner <telegram id>`           | Register an owner before the daemon starts       |
-| `mama tools install`                          | Install or update the document toolkit           |
-| `mama secret set <NAME>` / `mama secret list` | Rotate a token / list names only                 |
-| `mama daemon`                                 | Run the configured daemon in the foreground      |
-| `mama backfill <file>`                        | Write a prepared past-period backfill file       |
-| `mama replay`                                 | Replay prepared historical inputs in day windows |
-| `mama status` / `mama stop`                   | Report running/stopped / stop the process        |
+`node packages/standalone/dist/cli/index.js` in place of `mama`. Setup reads its answers from
+`MAMA_INIT_*` variables and opens a page in the browser on this machine, where the owner enters the
+bot token and the pairing code; nothing secret goes through the chat or a terminal. Sign in to the
+backend first; setup checks it, writes the setup, registers the first owner, installs the document
+toolkit and starts the service.
+
+For Telegram's common session, create a group with the bot, even for a solo owner, and send
+`/bind` there when setup asks. Private chats always enter personal sessions.
+Setup pairs you through a code the bot sends you and registers you as the first owner; `mama register-owner <telegram id>` registers
+another owner while the daemon is stopped.
+
+| Command                                            | Purpose                                              |
+| -------------------------------------------------- | ---------------------------------------------------- |
+| `mama init --non-interactive`                      | Set up and start MAMA, with the first owner          |
+| `mama init --section connectors --non-interactive` | Enable sources, with MAMA stopped; the agent runs it |
+| `mama register-owner <telegram id>`                | Register another owner while MAMA is stopped         |
+| `mama tools install`                               | Install or update the document toolkit               |
+| `mama secret set <NAME>` / `mama secret list`      | Rotate a token / list names only                     |
+| `mama daemon`                                      | Run the configured daemon in the foreground          |
+| `mama backfill <file>`                             | Write a prepared past-period backfill file           |
+| `mama replay`                                      | Replay prepared historical inputs in day windows     |
+| `mama status` / `mama stop`                        | Report running/stopped / stop the process            |
 
 See [CLI flags](../../docs/reference/cli.md) and
 [launchd management](../../docs/guides/troubleshooting.md).
@@ -71,8 +85,8 @@ and viewer sources/assets in `ui/` and `public/viewer/`.
 ## Data, security and status
 
 OS state lives in `~/.mama/`; its database defaults to `~/.mama/memory.db`.
-`config.yaml` and `connectors.json` hold settings; terminal-entered credentials live in
-`auth.env` (0600). Both backends have workspace-only writes and credential-read exclusions.
+`config.yaml` and `connectors.json` hold settings; credentials, entered on the setup page or at a
+terminal, live in `auth.env` (0600). Both backends have workspace-only writes and credential-read exclusions.
 The viewer binds to `127.0.0.1:3847` by default; remote data access requires a bearer token
 or verified Access JWT. See [security](../../docs/guides/security.md).
 

package/db/migrations/002-model-runs-parent-index.sql

@@ -0,0 +1,11 @@
+-- A run's child runs are read by parent, and only the product reads them that way: the upkeep and
+-- record-order runners wait for an order run's children, and the write-back scan reads and checks
+-- each question turn with its children. Core never queries by parent, so the index lives with the
+-- package that does. Without it every lookup scans model_runs; on a copy of a live install the
+-- write-back scan took about 3 s per pass, and about 50 ms with this index.
+CREATE INDEX IF NOT EXISTS idx_model_runs_parent
+  ON model_runs(parent_model_run_id)
+  WHERE parent_model_run_id IS NOT NULL;
+
+INSERT OR IGNORE INTO schema_version (source, version, description)
+VALUES ('standalone', 2, 'Index model runs by parent run, for the product runners that read children');

package/db/migrations/003-upkeep-settled.sql

@@ -0,0 +1,15 @@
+-- Upkeep subjects the runner has settled for good: checked, or lost after its last attempt.
+-- Attempts are counted from the stored order rows, and the mailbox deletes acked rows after seven
+-- days, so without this record a subject whose scan has no time bound (the board reconcile's stale
+-- items) would be ordered three more times every week, kept or lost. A settled subject is never
+-- ordered again; new work on the same thing is a new subject with a new key.
+CREATE TABLE IF NOT EXISTS upkeep_settled (
+  kind TEXT NOT NULL,
+  subject_key TEXT NOT NULL,
+  state TEXT NOT NULL CHECK (state IN ('checked', 'lost')),
+  settled_at INTEGER NOT NULL,
+  PRIMARY KEY (kind, subject_key)
+);
+
+INSERT OR IGNORE INTO schema_version (source, version, description)
+VALUES ('standalone', 3, 'Upkeep subjects settled for good, kept past the mailbox retention');

package/dist/api/google-read-actions.d.ts

@@ -0,0 +1,30 @@
+import type { ActionRegistration } from '@jungjaehoon/mama-core';
+import type { GwsCall } from './drive-actions.js';
+export declare const GOOGLE_READ_ACTION = "google.read";
+/**
+ * The read methods, per service, as gws takes them after the service name. The connectors call
+ * most of them; `users labels list` names the label ids messages carry. Drive's listing, file
+ * metadata and downloads are drive.read and drive.download; only a Google Doc, Sheet or Slides
+ * file read as text is new here.
+ */
+export declare const GOOGLE_READ_METHODS: {
+    readonly gmail: readonly ["users getProfile", "users labels list", "users messages list", "users messages get", "users threads list", "users threads get"];
+    readonly calendar: readonly ["calendarList list", "events list", "events get"];
+    readonly drive: readonly ["files export"];
+    readonly sheets: readonly ["spreadsheets get", "spreadsheets values get"];
+};
+export type GoogleService = keyof typeof GOOGLE_READ_METHODS;
+/**
+ * About 25,000 tokens of ASCII JSON: Claude Code's default limit for one MCP tool result, which a
+ * code_act return meets, while a Codex turn takes the result whole. Japanese or Korean text costs
+ * about a token per character, so a page of it near the cap is several times that. A page over it
+ * is narrowed by the request, not cut: cut JSON does not parse.
+ */
+export declare const GOOGLE_READ_MAX_CHARS = 100000;
+export interface GoogleReadPorts {
+    /** A directory only the daemon reads (under the MAMA home's runtime/): each call's own cwd. */
+    scratchDir: string;
+    gws?: GwsCall;
+}
+export declare function googleReadActionRegistrations(ports: GoogleReadPorts): ActionRegistration[];
+//# sourceMappingURL=google-read-actions.d.ts.map

package/dist/api/google-read-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-read-actions.d.ts","sourceRoot":"","sources":["../../src/api/google-read-actions.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AASjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;CAYtB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,SAAU,CAAC;AAqB7C,MAAM,WAAW,eAAe;IAC9B,+FAA+F;IAC/F,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAiFD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,eAAe,GAAG,kBAAkB,EAAE,CAyJ1F"}