monarchai 0.0.1 → 2.0.0

package/LICENSE

@@ -1,14 +1,177 @@
-monarchai — Notice
+Monarch CLI — Software License
 Copyright (c) 2026 Cymela, Republic of Serbia.
 All rights reserved.
 
-This package is published as a name reservation for the Monarch model line by
-Cymela. It contains no functional software.
+THIS IS A PROPRIETARY LICENSE. IT IS NOT AN OPEN-SOURCE LICENSE.
 
-No licence is granted to use the "Cymela", "Monarch" or "Hyper" names, or any
-associated marks, to identify another product or service, or in any way likely
-to cause confusion as to origin.
+It permits you to install and use the Monarch CLI, including for commercial
+work, at no cost. It does not permit you to redistribute it, sell it, or
+publish modified versions of it. If that is what you need, ask.
 
-The metadata file included in this package may be read and inspected freely.
+This license accompanies the Cymela Terms of Use ("the Terms"), published
+at https://cymela.com/terms. Where the Terms refer to a LICENSE file
+distributed with a component of the Services, this is that file. It is written
+to be consistent with Section 05 of the Terms, not to displace it.
 
-Contact: contact@cymela.com
+
+1. GRANT
+
+Subject to your compliance with this license and with the Terms, the copyright
+holder grants you a personal, worldwide, royalty-free, non-exclusive,
+revocable license to install and use the Monarch CLI for any lawful purpose,
+including commercial work.
+
+You may install it on as many machines as you personally use or control, and
+you may use it on private, confidential or commercial codebases. Nothing you
+create with it belongs to the copyright holder: your code, your prompts and
+your output are yours, and no part of them is transmitted to the copyright
+holder in the course of ordinary use.
+
+
+2. WHAT THIS LICENSE DOES NOT GRANT
+
+Except as stated in Section 1, no rights are granted. In particular, you may
+not, without prior written permission:
+
+  (a) distribute, publish, sublicense, rent, lease, lend, sell or otherwise
+      make the software available to third parties, whether modified or not,
+      and whether for a fee or not;
+
+  (b) publish or distribute a modified version, a fork, or a derivative work;
+
+  (c) incorporate the software, or a substantial part of it, into another
+      product or service that you distribute;
+
+  (d) remove, obscure or alter any copyright, license or attribution notice;
+
+  (e) represent any modified build as an official Cymela or Monarch CLI
+      release, or use the Cymela name, the Monarch CLI name, or either logo
+      in a way that suggests endorsement or affiliation;
+
+  (f) copy or reuse the software's source code, its structure and organization,
+      its user-interface layout, its visual design, its prompt text or its
+      written content in any other product or service, whether or not that
+      product competes with the Monarch CLI, and whether or not the copied
+      material is reproduced verbatim;
+
+  (g) offer the software, or any product substantially derived from it, to
+      third parties as a hosted, managed or software-as-a-service offering; or
+
+  (h) reverse engineer, decompile or disassemble the software, except to the
+      extent this restriction cannot lawfully be excluded (see below).
+
+Modifying your own installation for your own use is permitted. Publishing the
+result is what is not.
+
+Nothing in this section restricts any right you hold under mandatory law that
+cannot be excluded by agreement. For users in the European Union in particular,
+nothing here restricts the rights granted by Articles 5 and 6 of Directive
+2009/24/EC on the legal protection of computer programs, including observing or
+studying the program to determine its underlying ideas, and decompilation for
+interoperability purposes. Copyright protects the expression of this software,
+not the ideas or functionality behind it.
+
+
+3. CONDITIONS OF USE
+
+This license is conditional on your compliance with the acceptable-use terms
+in Section 06 of the Terms. In summary, and without limiting them, you must
+not use the software to break the law, to harm people, or in violation of the
+terms of the model provider whose API you connect it to.
+
+You must not rely on the software, without qualified human review, where an
+error could cause death, personal injury, or severe environmental, financial
+or infrastructural damage. It is a developer productivity tool. It is not
+certified, validated or fit for safety-critical use of any kind.
+
+You are responsible for reviewing what the agent proposes before you approve
+it, and for everything you produce with it.
+
+
+4. THIRD-PARTY COMPONENTS
+
+The Monarch CLI depends on third-party open-source packages, which are
+installed from their own sources and are not covered by this license. Each
+remains subject to the license its authors published it under, and those
+licenses govern your rights in those components. This license applies only to
+the Monarch CLI itself.
+
+Language models are not part of the software. The CLI is a client for a model
+you choose and pay for, reached with an API key belonging to you. The model
+provider's terms govern that relationship, not this license.
+
+
+5. TRADEMARKS
+
+The Cymela name, the Monarch CLI name, and the logos and visual identity of
+either are not licensed to you. Nothing here claims the ordinary word
+"monarch" outside its use as the name of this software. Section 1 is a license
+to use the software; it is not a grant of the brand.
+
+
+6. NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTY OF ANY
+KIND, WHETHER EXPRESS, IMPLIED OR STATUTORY. TO THE FULLEST EXTENT PERMITTED
+BY APPLICABLE LAW, ALL IMPLIED WARRANTIES ARE DISCLAIMED, INCLUDING ANY
+IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE,
+ACCURACY AND NON-INFRINGEMENT.
+
+There is no warranty that the software will be uninterrupted, secure or
+error-free, that defects will be corrected, or that any output will be
+accurate, complete, safe or reliable. You use it at your own risk, and you are
+solely responsible for any damage to your system, loss of data, or loss of
+work that results.
+
+
+7. LIMITATION OF LIABILITY
+
+TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAW, THE COPYRIGHT HOLDER WILL
+NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY
+OR PUNITIVE DAMAGES, NOR FOR ANY LOSS OF PROFITS, REVENUE, BUSINESS, GOODWILL,
+DATA OR WORK PRODUCT, ARISING OUT OF OR RELATING TO YOUR USE OF OR INABILITY
+TO USE THE SOFTWARE — WHETHER IN CONTRACT, TORT (INCLUDING NEGLIGENCE),
+STRICT LIABILITY OR OTHERWISE, AND WHETHER OR NOT THE POSSIBILITY OF SUCH
+DAMAGES WAS KNOWN.
+
+This expressly includes loss or damage arising from code the agent generated,
+modified, deleted or executed; from output produced by a third-party model;
+from the act or omission of any third-party provider; or from another person's
+misuse of the software.
+
+Total aggregate liability will not exceed the greater of (a) the amount you
+have paid the copyright holder for the software in the twelve months preceding
+the claim, which for free software is zero, or (b) EUR 100.
+
+Nothing here excludes or limits liability for death or personal injury caused
+by negligence, for fraud or fraudulent misrepresentation, or for anything else
+that cannot lawfully be excluded. If you are a consumer, you keep every
+mandatory right your local consumer-protection law gives you.
+
+
+8. TERMINATION
+
+This license ends automatically and immediately if you breach it or the Terms.
+On termination you must stop using the software and delete your copies.
+Continuing to use it after termination is unlicensed use of a copyrighted
+work. Sections 2 and 5 to 10 survive termination.
+
+
+9. GOVERNING LAW
+
+This license is governed by the laws of the Republic of Serbia, without regard
+to its conflict-of-laws rules, and the courts of the Republic of Serbia have
+exclusive jurisdiction. If you use the software as a consumer resident in the
+European Union, the United Kingdom, or another jurisdiction whose law gives
+you a mandatory right to your local courts, this does not deprive you of it.
+
+
+10. RELATIONSHIP TO THE TERMS
+
+This license and the Terms are intended to be read together. Where they
+genuinely conflict on the scope of the license granted in Section 1, this file
+prevails, as Section 05 of the Terms provides. On every other subject the
+Terms apply in full.
+
+
+Questions, permissions and licensing enquiries: contact@cymela.com

package/MONARCH.md

@@ -0,0 +1,10 @@
+# Monarch — install-level notes (loaded every turn)
+
+The full operating protocol (ReACT loop, tool catalog, anti-loop, formatting)
+is built in and always active — do not re-derive it from here.
+
+Install-level additions only:
+
+- **Attachments**: vision extract = ground truth for an image. Paths under `.monarch/attachments/` are real files.
+- **Plan → Execute**: `/run-plan` switches to Default and seeds implementation. Follow the plan; don't re-research unless blocked.
+- **Tone**: brief; lead with the answer; no filler. Never claim success without tool output.

package/README.md

@@ -1,35 +1,126 @@
-# monarchai
+# Monarch CLI
 
-**Reserved for the Monarch model line by Cymela.** See <https://cymela.com>.
+Premium terminal coding agent, by [Cymela](https://cymela.com).
 
-## What this is
+Monarch is an agentic CLI: you describe the change, it reads, plans, edits,
+runs and verifies — inside your workspace, with your permission model, on the
+provider of your choice.
 
-A name reservation, held by the project it names. **Monarch** is Cymela's model
-line; its frontier tier is called **Hyper**. This package is the npm home for
-that line and is published so the name is not taken by an unrelated project.
+## Highlights
 
-It has no runtime behaviour yet. Requiring it returns metadata describing what
-the name is held for:
+- **Verification-first engine.** A deterministic guard chain (verification
+  gate, task ladder, close-out audit, anti-loop counters) sits between the
+  model and "done" — the agent proves its work instead of asserting it.
+- **Provider-neutral.** OpenAI-compatible, Anthropic and Gemini wire formats;
+  OpenRouter, local llama.cpp servers, gateways and proxies via
+  `MONARCH_BASE_URL`. Parameter quirks are learned from provider errors, not
+  hard-coded.
+- **Sub-agents with roles.** Scout (read-only), Builder, Checker — tool-gated,
+  depth-limited, streamed live into the agents panel (`/agents`, Alt+A).
+- **Batch tools.** Recoverable multi-file edits (`multi-edit`), ranged and
+  multi-ranged reads (`read-many`, `#L15-29, #L128-236`) so the agent touches
+  exactly what it needs.
+- **Sessions, undo, cost.** Every turn is persisted (`/sessions`, which also
+  starts a fresh one in the same folder),
+  checkpointed (`/undo`, binary-safe file restore with conflict reporting), and metered (`/usage`,
+  auto-compaction before the context window overflows).
+- **Memory.** It remembers durable, personal things across sessions and
+  projects — preferences, standing decisions, names and dates you tell it to
+  hold — on your machine, at `~/.monarch/memory.json`, mode 0600. The contents
+  are never in the prompt: the model gets a list of group names and recalls
+  when a turn needs one. `/memory` shows everything, `/memory add` writes one
+  yourself, `/memory off` stops it collecting.
+- **Themes.** Eight of them (`/theme`). Yes, including `mono` for purists.
 
-```js
-require('monarchai');
-// { name: 'monarchai', reservedFor: 'Monarch — the model line by Cymela', status: 'reserved', … }
+## Install
+
+```bash
+npm install -g monarchai
+```
+
+Then, in any project folder:
+
+```bash
+monarch
+```
+
+`npm install -g cymela` installs exactly the same thing and gives you the same
+`monarch` command — Cymela is the project, Monarch CLI is what it ships, and
+either name works.
+
+Nothing is compiled and there are no runtime dependencies — the install is a
+single bundled file. (Commands run through pipes; if you need a real pty for
+programs that prompt, `npm install -g @homebridge/node-pty-prebuilt-multiarch`
+and Monarch will pick it up. `monarch --doctor` reports which backend is in
+use.)
+
+Node 20+. First run walks through provider, key and model, then drops you into
+the folder you started it in; after that `monarch` goes straight to the prompt.
+Keys can also come from the environment (`MONARCH_API_KEY`,
+`OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, …), in which case the first run
+skips straight past asking for one.
+
+## In a script
+
+```bash
+monarch -p "summarise the uncommitted changes"
+```
+
+One turn, no TUI. The answer goes to stdout and nothing else does — tool
+activity and errors go to stderr — so it pipes. `--mode plan`, `--effort max`,
+`--model <id>` and `--thinking` all apply. Exit code 0 when the turn finished,
+1 when it did not, 2 when it is not set up yet.
+
+## When something is wrong
+
+```bash
+monarch --doctor
 ```
 
-## What this is not
+Checks Node, the terminal, the provider, whether the key is actually accepted,
+the model, file permissions, the shell backend and the workspace — and prints
+the command to fix each failure. `/doctor` runs the same checks from inside a
+session.
+
+## Configuration
+
+| Variable | Effect |
+| --- | --- |
+| `MONARCH_BASE_URL` | Endpoint override (local models, gateways, proxies) |
+| `MONARCH_REQUEST_TIMEOUT_MS` | Connect+headers timeout (default 1h, `0` disables) |
+| `MONARCH_STALL_TIMEOUT_MS` | Mid-stream silence watchdog (default 5min, `0` disables) |
+
+Project instructions live in `MONARCH.md` (legacy `CYMELA.md`, `HYPER.md` and
+`SYNTH.md` are honoured) — offered on first run in a folder, never written
+without asking. Skills live in `SKILLS.md`. Session data stays in `.monarch/`
+in your workspace, git-ignored automatically. What Monarch remembers about
+*you* is separate and machine-wide: `~/.monarch/memory.json`, readable with
+`/memory`, and nothing leaves this machine except inside a request to the
+provider you chose.
+
+## License
 
-- **Not the Cymela CLI.** The terminal coding agent is published separately as
-  [`cymela`](https://www.npmjs.com/package/cymela) and installs with
-  `npm install -g cymela`. That package and its `cymela` command are unaffected
-  by this reservation.
-- **Not a released model.** Nothing here downloads, runs, or provides access to
-  a model.
+Proprietary — free to install and use, including commercially; no
+redistribution or modified republishing. See [LICENSE](LICENSE).
 
-## Naming
+## Execution and recovery boundaries
 
-Cymela is the company. Monarch is the model line. Hyper is the frontier tier
-within that line — so a release reads *Monarch Hyper*, never *Cymela Hyper*.
+Plan mode permits native inspection tools and a small set of literal shell reads.
+Scripts, test runners, linters, interpreters, and raw git commands need Agent mode
+and execution approval. Use the structured git tool for inspection in Plan mode.
+The model can enter Plan mode, but only the user can leave it or enable Auto.
+Headless writes require `--mode auto` or a global `permissions.approvedTools` entry.
+Shell approval is not an OS sandbox: approved commands run with the user's host
+permissions. Use an isolated container or VM when executing untrusted project code.
 
-## Contact
+Multi-edit validates and stages every replacement before committing. Commit
+failures trigger rollback. A crash or incomplete rollback leaves original bytes
+and a manifest under `.monarch/recovery/`; preserve that directory and inspect
+the manifest and current files before restoring anything. Individual file
+replacement is atomic; a multi-file batch is not crash-atomic.
+Undo retains checkpoints when restoration fails and refuses to overwrite changes
+made after a tool completed. Shell and directory operations may leave changes
+outside individual file backups.
 
-<contact@cymela.com> · <https://cymela.com>
+Web fetching validates and pins DNS addresses at every redirect. Pages are limited
+to 2 MB of transferred and decoded content and a 30-second request deadline.