gravity-cli 0.5.6__tar.gz → 0.6.0__tar.gz

{gravity_cli-0.5.6 → gravity_cli-0.6.0}/AGENT_STANDARD.md

@@ -25,7 +25,7 @@ my-agent/
 ```
 
 **Only these are bundled.** `gravity build` zips exactly `manifest.yaml`,
-`requirements.txt`, `requirements.lock`, and the contents of `src/` and
+`requirements.txt`, `requirements.lock`, `tools_needed.yaml` (if present), and the contents of `src/` and
 `tests/` (minus `__pycache__`). Anything else — `.venv/`, `build/`, notebooks,
 a `data/` folder — is not shipped, and code that reads it will fail at runtime.
 
@@ -41,14 +41,14 @@ runtime:
   framework: langgraph            # only value accepted
   python: "3.12"                  # the platform runs 3.12; validate refuses any other
   entrypoint: src/agent.py:graph  # file:object — see §3
-  timeout_seconds: 300            # 10–900
+  timeout_seconds: 300            # 10–28800
 
 dependencies:
   lockfile: requirements.lock     # leave as-is
 
 inputs:                           # becomes the consumer's form; arrives as state["inputs"]
   - name: query                   # the key in state["inputs"]
-    type: text                    # text | textarea | number | boolean | static-dropdown | email | url | date | file
+    type: text                    # text | textarea | number | boolean | static-dropdown | email | url | date | secret | file
     label: "What should I do?"    # what the consumer sees
     required: true
     # options: [a, b]             # static-dropdown only
@@ -69,6 +69,7 @@ triggers:                         # optional — what starts a run
   # schedule:
   #   cron: "0 9 * * 1"           # 5 fields: digits, * / , - only (no @daily, no MON); every 5 minutes at the fastest; one day field at most; Asia/Kolkata
   #   consumer_can_change: true
+  # webhook: [github.push]        # run on a GitHub push; the only source today
 
 approvals:                        # optional — tools that pause the run for the consumer's yes
   required_for: []                # each must also be in permissions.tools
@@ -127,9 +128,10 @@ runner is too old, not your agent.
 
 **State.** The runtime invokes `graph.astream({"inputs": {...}}, stream_mode="updates")`
 — the keyword is passed only when your `astream` accepts it, so a hand-rolled
-object with a plain `astream(state)` works too (accepting `**kwargs` is the
-safe habit). The dict is the
-dict is the consumer's form answers keyed by `inputs[].name`. Your state
+object with a plain `astream(state)` works in `gravity run` (accepting `**kwargs`
+is the safe habit). The hosted platform needs a compiled LangGraph graph: it
+injects its own checkpointer and store into it. The dict is the
+consumer's form answers keyed by `inputs[].name`. Your state
 therefore needs:
 
 ```python
@@ -259,7 +261,7 @@ leave their record in `.gravity/runs/`; one run is live per folder).
 
 | Stage | Catches |
 |---|---|
-| `gravity validate` / `build` (local) | manifest schema · entrypoint file + object exist (static) · `requirements.txt` present · lockfile compiles for aarch64 · undeclared network imports (warning) |
+| `gravity validate` / `build` (local) | manifest schema · entrypoint file + object exist (static) · `requirements.txt` present · lockfile compiles for aarch64 · undeclared tool names in source (an error for a write tool, a warning for a read tool) |
 | `gravity push` (server) | manifest re-validated with the same rules · `permissions.tools` all exist in the catalog · version not already published |
 | deploy | every pin in the lock installs on ARM64 |
 | first run | module imports · `graph` resolves to something with `astream()` · state has `inputs` · final state has `result` |

gravity_cli-0.5.6/README.md → gravity_cli-0.6.0/PKG-INFO

@@ -1,3 +1,20 @@
+Metadata-Version: 2.5
+Name: gravity-cli
+Version: 0.6.0
+Summary: gravity cli — init, run, and push python agents to the Gravity marketplace
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.12
+Requires-Dist: gravity-schema==0.6.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Requires-Dist: uv>=0.8.0
+Description-Content-Type: text/markdown
+
 <h1 align="center">Gravity CLI</h1>
 
 <p align="center">
@@ -75,7 +92,7 @@ gravity init my-agent
 
 ## Declare it once, enforced on every call
 
-There is no SDK to learn. Your agent is plain LangGraph that reads three environment variables. Everything Gravity enforces comes from `manifest.yaml`:
+There is almost no SDK to learn. Your agent is plain LangGraph that reads three environment variables; the one Gravity package, `gravity`, is preinstalled on the platform and is only needed to load approval-gated tools. Everything Gravity enforces comes from `manifest.yaml`:
 
 | You declare in `manifest.yaml` | What Gravity does with it |
 |---|---|
@@ -91,11 +108,11 @@ The same rules apply on your laptop and when the agent runs hosted, because both
 
 | | |
 |---|---|
-| Commands | 18, grouped into build an agent, publish, your agents, account and help |
+| Commands | 21, grouped into build an agent, publish, your agents, account, help and Gravity CLI |
 | Starter templates | 4: `minimal`, `structured`, `deepagent`, `chat` |
-| Tool catalog | 1,402 tools across 15 apps (Gmail, Slack, Linear, GitHub, Calendar, Drive, Sheets, LinkedIn, Jira, Confluence, Notion, WhatsApp, web search, and two built-ins), 28 of them curated |
-| Test suite | 466 tests (214 CLI, 252 schema), run on Ubuntu and Windows with Python 3.12 and 3.13 |
-| Runtime contract | 3 environment variables, no Gravity import in your code |
+| Tool catalog | 1,405 tools across 12 apps (Gmail, Slack, Linear, GitHub, Calendar, Drive, Sheets, LinkedIn, Jira, Confluence, Notion, WhatsApp), plus web search, Firecrawl and two built-ins; 31 of them curated |
+| Test suite | 543 tests (285 CLI, 258 schema), run on Ubuntu and Windows with Python 3.12 and 3.13 |
+| Runtime contract | 3 environment variables; an optional `import gravity` only for approval-gated tools |
 
 ## Five things to know before you start
 
@@ -194,6 +211,9 @@ Run `gravity help` for this list in the terminal, and add `-h` to any command fo
 | | [`gravity connect`](#gravity-connect) | Connect an account your agents act on (Gmail, Slack...) |
 | **Help** | [`gravity guide`](#gravity-guide) | Read the builder guide: how to build a good agent |
 | | [`gravity help`](#gravity-help) | Show the list of commands |
+| **Gravity CLI** | [`gravity docs`](#gravity-docs) | Write `Gravity.agent.md` for the coding agent in this folder |
+| | [`gravity update`](#gravity-update) | Update to the latest release and see what is new |
+| | [`gravity changelog`](#gravity-changelog) | What changed in each release |
 
 `gravity --api-url URL <command>` saves a different control-plane address to `~/.gravity/config.json`; it must start with `http://` or `https://`. The flag applies to the command it is given with; on later commands a `GRAVITY_API_URL` in `~/.gravity/.env` or the shell still wins over `config.json`, and the CLI says so when that is the case. `gravity --version` (or `-V`) prints the installed version. Wherever a command takes `[path]`, it is the agent's folder and defaults to the current one.
 
@@ -412,7 +432,7 @@ gravity logs <run_id>
 
 Browse the tool catalog: the names you can put under `permissions.tools`, with what each one does. It is the gateway's own list, so it shows exactly what a run can call, and it needs no sign-in.
 
-About 25 tools are curated, such as `gmail.read` and `web.search`. The other ~1,100 are imported from the same apps and unreviewed: any imported tool that changes something must also be under `approvals.required_for`, and `gravity validate` checks that.
+31 tools are curated, such as `gmail.read` and `web.search`. The other ~1,370 are imported from the same apps and unreviewed: any imported tool that changes something must also be under `approvals.required_for`, and `gravity validate` checks that.
 
 ```
 gravity tools [search]
@@ -485,6 +505,46 @@ gravity guide --save
 gravity guide | less
 ```
 
+### `gravity docs`
+
+Write or refresh the two files a coding agent needs to build for Gravity in this folder: `Gravity.agent.md` (how Gravity runs agents, the manifest, every tool this release knows, the output formats, the rules that fail a load) and `problem-to-agent.md` (the method for turning a problem statement into an agent that holds up).
+
+```
+gravity docs [--force]
+```
+
+| Option | Description |
+|---|---|
+| `--force` | Replace the files even where you edited them, or where a file Gravity did not write has the same name |
+
+You rarely need this. Every command writes the two files into the folder it runs in if they are missing (never into your home folder or a drive root; `gravity init` writes them into the new agent), and rewrites them when a newer release changes them. The first line of a file Gravity wrote names the release and a hash of the text after it: if you edit the file the hash no longer matches and Gravity leaves it alone. Your own `agent.md`, `AGENTS.md` and `CLAUDE.md` are never touched. Point your coding agent at `Gravity.agent.md` from them if it does not look there by itself. Set `GRAVITY_AGENT_DOCS=0` to stop the automatic writes.
+
+### `gravity update`
+
+Check PyPI for a newer release, install it, and show what is new.
+
+```
+gravity update [--check]
+```
+
+| Option | Description |
+|---|---|
+| `--check` | Only say whether a newer release exists |
+
+You do not have to run it: once every six hours a command looks for a newer release, and when there is one it says `Update available 0.6.0 → 0.6.1`, updates, and runs your command again as the new version, which lists what changed. It upgrades the way you installed it (`uv tool` or `pipx`); a copy installed any other way, or from a source checkout, is told the command to run and left alone. Nothing here can stop a command: a failed update is one warning and the command runs on the version you have. Set `GRAVITY_AUTO_UPDATE=0` to turn the check and the install off; CI never updates.
+
+### `gravity changelog`
+
+What changed in each release, written for builders.
+
+```
+gravity changelog [--all]
+```
+
+| Option | Description |
+|---|---|
+| `--all` | Every release, not only the one you are on |
+
 ### `gravity help`
 
 Show the list of commands. The same as `gravity -h`.
@@ -540,6 +600,9 @@ Set `GRAVITY_API_URL` and `GRAVITY_GATEWAY_URL` only to work against services yo
 | `GRAVITY_API_URL` | The control plane's address | `https://agents.dev.gravity.fast` |
 | `GRAVITY_API_TOKEN` | A control-plane dev token, used instead of `gravity login`. For development only. | none |
 | `GRAVITY_CONFIG_DIR` | Moves `~/.gravity` elsewhere. Useful for tests and CI. | `~/.gravity` |
+| `GRAVITY_AUTO_UPDATE` | When `0`, commands neither check for a newer release nor install one. Always off when `CI` is set. | `1` |
+| `GRAVITY_AGENT_DOCS` | When `0`, commands do not write `Gravity.agent.md` and `problem-to-agent.md` into the folder they run in. `gravity docs` still does. | `1` |
+| `GRAVITY_UPDATE_URL` | Where the latest version is read from, a JSON document with `info.version`. For tests and mirrors. | PyPI |
 | `GRAVITY_UNATTENDED` | When `1`, calls that need approval are rejected without asking. `gravity schedule` sets it for you. | unset |
 
 ### What your agent receives
@@ -775,6 +838,7 @@ Real tools act on a connected account. Connect one with `gravity-gateway connect
 
 ## What's new
 
+- **0.6.0** Gravity CLI keeps itself up to date and says what changed (`gravity update`, `gravity changelog`). `Gravity.agent.md` and `problem-to-agent.md` appear in the folder you work in, for your coding agent (`gravity docs`). `gravity` on its own shows your version, the agent in the folder, whether you are signed in, and any update. The notes shown after an update are `src/gravity_cli/CHANGELOG.md`.
 - **0.5.5** `manifest.yaml` takes an optional `display:` hint for how a run's result shows: `view` (document, report, table, chart, code or files), `field` (the result key to show) and `chart` (`type: line` or `bar`, `x`, and up to three `y` fields). It is a hint, never a rule: an unknown view or key is ignored, so it never fails a push. 0.5.4 and earlier refuse a manifest that has it.
 - **0.5.4** `gravity agents` shows each agent's review: a REVIEW column (not submitted, submitted, approved, rejected), and under "From the Gravity team" the reviewer's notes and what to do next. An agent the Gravity team turned off shows as `off` with the reason. UPDATED reads "3 min ago" instead of a timestamp, and status and review are coloured. Also, from a full audit of every command: `gravity --version`. Clear messages instead of tracebacks for: a proxy or sign-in page answering instead of Gravity, a refused `GRAVITY_API_TOKEN` or `GRAVITY_DEV_TOKEN`, an expired sign-in code, a non-UTF-8 manifest, an out-of-range `--port`, a missing agent folder, a malformed session file. `gravity validate` now refuses what the build would refuse: a `graph` that is not an async factory, `os.environ` or `asyncio.run` at import, relative imports, unquoted `python: 3.12`, schedules faster than every 5 minutes or with both day fields, out-of-range cron fields; it accepts a re-exported `graph`. `gravity agents` shows the review status and failure reasons; `gravity runs` never shortens an id; `gravity logs` never wraps. `gravity push` refuses a bundle over 30 MB or a manifest over 12 KB before uploading, and says why when a failed version is re-pushed. `gravity build` ships `tools_needed.yaml`, leaves dotfiles out, and refuses to build without `requirements.lock`. `gravity adapt` leaves the folder untouched when a model call fails. `gravity schedule` checks inputs before the first tick and runs on Asia/Kolkata like the hosted schedules. `gravity run` deletes `.gravity/payload.json` after the run, warns when no `.venv` is present, and keeps a plain agent's `result`. `gravity connect <app>` refuses on the shared test account instead of attaching your account to it. The builder guide and agent standard describe the real flow (init, validate, run or dev, build, push, review on /app).
 - **0.5.3** `gravity dev` opens a local dashboard for your agent: a form from your manifest, a live timeline, approvals, the result and run history; runs from `gravity run` in the same folder show up in it live, and the other way round. WhatsApp joins the catalog (51 tools; 1,402 across 15 apps including the curated and built-in ones). Agents can return generated images: put them in a corpus section's `images` and they land in the Word, PowerPoint and Markdown outputs. The agent standard now shows how to generate images and embeddings through the gateway. `NEEDS_RECONNECT` on the shared test account tells you to ask Gravity, not to connect your own account.
@@ -858,6 +922,8 @@ uv run python -m gravity_schema.gen_catalog --root <platform repo>/code-first
 | Document | What it covers |
 |---|---|
 | [Builder guide](src/gravity_cli/BUILDER_GUIDE.md) | How to build a good agent, start to finish, with a complete example. Also `gravity guide` |
+| [`Gravity.agent.md`](src/gravity_cli/docs/Gravity.agent.md) | The guide `gravity docs` writes for coding agents; its tool list is filled in from the catalog of the release that writes it |
+| [`problem-to-agent.md`](src/gravity_cli/docs/problem-to-agent.md) | The method for turning a problem statement into an agent that holds up |
 | [Agent standard](AGENT_STANDARD.md) | The exact rules an agent must follow |
 | [Templates](TEMPLATES.md) | The four templates and when to pick each |
 | [`manifest.schema.json`](packages/gravity-schema/schema/manifest.schema.json) | The manifest as a machine-readable JSON Schema |

gravity_cli-0.5.6/PKG-INFO → gravity_cli-0.6.0/README.md

@@ -1,20 +1,3 @@
-Metadata-Version: 2.5
-Name: gravity-cli
-Version: 0.5.6
-Summary: gravity cli — init, run, and push python agents to the Gravity marketplace
-License-Expression: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Requires-Python: >=3.12
-Requires-Dist: gravity-schema==0.5.6
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: keyring>=25.0.0
-Requires-Dist: python-dotenv>=1.0.0
-Requires-Dist: rich>=13.9.0
-Requires-Dist: typer>=0.15.0
-Requires-Dist: uv>=0.8.0
-Description-Content-Type: text/markdown
-
 <h1 align="center">Gravity CLI</h1>
 
 <p align="center">
@@ -92,7 +75,7 @@ gravity init my-agent
 
 ## Declare it once, enforced on every call
 
-There is no SDK to learn. Your agent is plain LangGraph that reads three environment variables. Everything Gravity enforces comes from `manifest.yaml`:
+There is almost no SDK to learn. Your agent is plain LangGraph that reads three environment variables; the one Gravity package, `gravity`, is preinstalled on the platform and is only needed to load approval-gated tools. Everything Gravity enforces comes from `manifest.yaml`:
 
 | You declare in `manifest.yaml` | What Gravity does with it |
 |---|---|
@@ -108,11 +91,11 @@ The same rules apply on your laptop and when the agent runs hosted, because both
 
 | | |
 |---|---|
-| Commands | 18, grouped into build an agent, publish, your agents, account and help |
+| Commands | 21, grouped into build an agent, publish, your agents, account, help and Gravity CLI |
 | Starter templates | 4: `minimal`, `structured`, `deepagent`, `chat` |
-| Tool catalog | 1,402 tools across 15 apps (Gmail, Slack, Linear, GitHub, Calendar, Drive, Sheets, LinkedIn, Jira, Confluence, Notion, WhatsApp, web search, and two built-ins), 28 of them curated |
-| Test suite | 466 tests (214 CLI, 252 schema), run on Ubuntu and Windows with Python 3.12 and 3.13 |
-| Runtime contract | 3 environment variables, no Gravity import in your code |
+| Tool catalog | 1,405 tools across 12 apps (Gmail, Slack, Linear, GitHub, Calendar, Drive, Sheets, LinkedIn, Jira, Confluence, Notion, WhatsApp), plus web search, Firecrawl and two built-ins; 31 of them curated |
+| Test suite | 543 tests (285 CLI, 258 schema), run on Ubuntu and Windows with Python 3.12 and 3.13 |
+| Runtime contract | 3 environment variables; an optional `import gravity` only for approval-gated tools |
 
 ## Five things to know before you start
 
@@ -211,6 +194,9 @@ Run `gravity help` for this list in the terminal, and add `-h` to any command fo
 | | [`gravity connect`](#gravity-connect) | Connect an account your agents act on (Gmail, Slack...) |
 | **Help** | [`gravity guide`](#gravity-guide) | Read the builder guide: how to build a good agent |
 | | [`gravity help`](#gravity-help) | Show the list of commands |
+| **Gravity CLI** | [`gravity docs`](#gravity-docs) | Write `Gravity.agent.md` for the coding agent in this folder |
+| | [`gravity update`](#gravity-update) | Update to the latest release and see what is new |
+| | [`gravity changelog`](#gravity-changelog) | What changed in each release |
 
 `gravity --api-url URL <command>` saves a different control-plane address to `~/.gravity/config.json`; it must start with `http://` or `https://`. The flag applies to the command it is given with; on later commands a `GRAVITY_API_URL` in `~/.gravity/.env` or the shell still wins over `config.json`, and the CLI says so when that is the case. `gravity --version` (or `-V`) prints the installed version. Wherever a command takes `[path]`, it is the agent's folder and defaults to the current one.
 
@@ -429,7 +415,7 @@ gravity logs <run_id>
 
 Browse the tool catalog: the names you can put under `permissions.tools`, with what each one does. It is the gateway's own list, so it shows exactly what a run can call, and it needs no sign-in.
 
-About 25 tools are curated, such as `gmail.read` and `web.search`. The other ~1,100 are imported from the same apps and unreviewed: any imported tool that changes something must also be under `approvals.required_for`, and `gravity validate` checks that.
+31 tools are curated, such as `gmail.read` and `web.search`. The other ~1,370 are imported from the same apps and unreviewed: any imported tool that changes something must also be under `approvals.required_for`, and `gravity validate` checks that.
 
 ```
 gravity tools [search]
@@ -502,6 +488,46 @@ gravity guide --save
 gravity guide | less
 ```
 
+### `gravity docs`
+
+Write or refresh the two files a coding agent needs to build for Gravity in this folder: `Gravity.agent.md` (how Gravity runs agents, the manifest, every tool this release knows, the output formats, the rules that fail a load) and `problem-to-agent.md` (the method for turning a problem statement into an agent that holds up).
+
+```
+gravity docs [--force]
+```
+
+| Option | Description |
+|---|---|
+| `--force` | Replace the files even where you edited them, or where a file Gravity did not write has the same name |
+
+You rarely need this. Every command writes the two files into the folder it runs in if they are missing (never into your home folder or a drive root; `gravity init` writes them into the new agent), and rewrites them when a newer release changes them. The first line of a file Gravity wrote names the release and a hash of the text after it: if you edit the file the hash no longer matches and Gravity leaves it alone. Your own `agent.md`, `AGENTS.md` and `CLAUDE.md` are never touched. Point your coding agent at `Gravity.agent.md` from them if it does not look there by itself. Set `GRAVITY_AGENT_DOCS=0` to stop the automatic writes.
+
+### `gravity update`
+
+Check PyPI for a newer release, install it, and show what is new.
+
+```
+gravity update [--check]
+```
+
+| Option | Description |
+|---|---|
+| `--check` | Only say whether a newer release exists |
+
+You do not have to run it: once every six hours a command looks for a newer release, and when there is one it says `Update available 0.6.0 → 0.6.1`, updates, and runs your command again as the new version, which lists what changed. It upgrades the way you installed it (`uv tool` or `pipx`); a copy installed any other way, or from a source checkout, is told the command to run and left alone. Nothing here can stop a command: a failed update is one warning and the command runs on the version you have. Set `GRAVITY_AUTO_UPDATE=0` to turn the check and the install off; CI never updates.
+
+### `gravity changelog`
+
+What changed in each release, written for builders.
+
+```
+gravity changelog [--all]
+```
+
+| Option | Description |
+|---|---|
+| `--all` | Every release, not only the one you are on |
+
 ### `gravity help`
 
 Show the list of commands. The same as `gravity -h`.
@@ -557,6 +583,9 @@ Set `GRAVITY_API_URL` and `GRAVITY_GATEWAY_URL` only to work against services yo
 | `GRAVITY_API_URL` | The control plane's address | `https://agents.dev.gravity.fast` |
 | `GRAVITY_API_TOKEN` | A control-plane dev token, used instead of `gravity login`. For development only. | none |
 | `GRAVITY_CONFIG_DIR` | Moves `~/.gravity` elsewhere. Useful for tests and CI. | `~/.gravity` |
+| `GRAVITY_AUTO_UPDATE` | When `0`, commands neither check for a newer release nor install one. Always off when `CI` is set. | `1` |
+| `GRAVITY_AGENT_DOCS` | When `0`, commands do not write `Gravity.agent.md` and `problem-to-agent.md` into the folder they run in. `gravity docs` still does. | `1` |
+| `GRAVITY_UPDATE_URL` | Where the latest version is read from, a JSON document with `info.version`. For tests and mirrors. | PyPI |
 | `GRAVITY_UNATTENDED` | When `1`, calls that need approval are rejected without asking. `gravity schedule` sets it for you. | unset |
 
 ### What your agent receives
@@ -792,6 +821,7 @@ Real tools act on a connected account. Connect one with `gravity-gateway connect
 
 ## What's new
 
+- **0.6.0** Gravity CLI keeps itself up to date and says what changed (`gravity update`, `gravity changelog`). `Gravity.agent.md` and `problem-to-agent.md` appear in the folder you work in, for your coding agent (`gravity docs`). `gravity` on its own shows your version, the agent in the folder, whether you are signed in, and any update. The notes shown after an update are `src/gravity_cli/CHANGELOG.md`.
 - **0.5.5** `manifest.yaml` takes an optional `display:` hint for how a run's result shows: `view` (document, report, table, chart, code or files), `field` (the result key to show) and `chart` (`type: line` or `bar`, `x`, and up to three `y` fields). It is a hint, never a rule: an unknown view or key is ignored, so it never fails a push. 0.5.4 and earlier refuse a manifest that has it.
 - **0.5.4** `gravity agents` shows each agent's review: a REVIEW column (not submitted, submitted, approved, rejected), and under "From the Gravity team" the reviewer's notes and what to do next. An agent the Gravity team turned off shows as `off` with the reason. UPDATED reads "3 min ago" instead of a timestamp, and status and review are coloured. Also, from a full audit of every command: `gravity --version`. Clear messages instead of tracebacks for: a proxy or sign-in page answering instead of Gravity, a refused `GRAVITY_API_TOKEN` or `GRAVITY_DEV_TOKEN`, an expired sign-in code, a non-UTF-8 manifest, an out-of-range `--port`, a missing agent folder, a malformed session file. `gravity validate` now refuses what the build would refuse: a `graph` that is not an async factory, `os.environ` or `asyncio.run` at import, relative imports, unquoted `python: 3.12`, schedules faster than every 5 minutes or with both day fields, out-of-range cron fields; it accepts a re-exported `graph`. `gravity agents` shows the review status and failure reasons; `gravity runs` never shortens an id; `gravity logs` never wraps. `gravity push` refuses a bundle over 30 MB or a manifest over 12 KB before uploading, and says why when a failed version is re-pushed. `gravity build` ships `tools_needed.yaml`, leaves dotfiles out, and refuses to build without `requirements.lock`. `gravity adapt` leaves the folder untouched when a model call fails. `gravity schedule` checks inputs before the first tick and runs on Asia/Kolkata like the hosted schedules. `gravity run` deletes `.gravity/payload.json` after the run, warns when no `.venv` is present, and keeps a plain agent's `result`. `gravity connect <app>` refuses on the shared test account instead of attaching your account to it. The builder guide and agent standard describe the real flow (init, validate, run or dev, build, push, review on /app).
 - **0.5.3** `gravity dev` opens a local dashboard for your agent: a form from your manifest, a live timeline, approvals, the result and run history; runs from `gravity run` in the same folder show up in it live, and the other way round. WhatsApp joins the catalog (51 tools; 1,402 across 15 apps including the curated and built-in ones). Agents can return generated images: put them in a corpus section's `images` and they land in the Word, PowerPoint and Markdown outputs. The agent standard now shows how to generate images and embeddings through the gateway. `NEEDS_RECONNECT` on the shared test account tells you to ask Gravity, not to connect your own account.
@@ -875,6 +905,8 @@ uv run python -m gravity_schema.gen_catalog --root <platform repo>/code-first
 | Document | What it covers |
 |---|---|
 | [Builder guide](src/gravity_cli/BUILDER_GUIDE.md) | How to build a good agent, start to finish, with a complete example. Also `gravity guide` |
+| [`Gravity.agent.md`](src/gravity_cli/docs/Gravity.agent.md) | The guide `gravity docs` writes for coding agents; its tool list is filled in from the catalog of the release that writes it |
+| [`problem-to-agent.md`](src/gravity_cli/docs/problem-to-agent.md) | The method for turning a problem statement into an agent that holds up |
 | [Agent standard](AGENT_STANDARD.md) | The exact rules an agent must follow |
 | [Templates](TEMPLATES.md) | The four templates and when to pick each |
 | [`manifest.schema.json`](packages/gravity-schema/schema/manifest.schema.json) | The manifest as a machine-readable JSON Schema |

{gravity_cli-0.5.6 → gravity_cli-0.6.0}/RELEASING.md

@@ -35,6 +35,8 @@ Three places must carry the same number:
 | `pyproject.toml` | `"gravity-schema==X.Y.Z"` under `dependencies` |
 | `packages/gravity-schema/pyproject.toml` | `version = "X.Y.Z"` |
 
+Add the release to `src/gravity_cli/CHANGELOG.md`: a `## X.Y.Z - date` heading and one `- new|improved|fixed: Headline. Detail.` line per change a builder would care about. It is what `gravity update` shows after an update, and `tests/test_changelog.py` fails a version that has no entry. Set the date to the day you tag.
+
 Then refresh the lockfile:
 
 ```bash
@@ -116,6 +118,8 @@ gh run rerun <run-id> --failed
 
 ## Rules
 
+- **A release reaches every installed CLI within about six hours.** Each command checks PyPI for a newer version and updates itself (`src/gravity_cli/updater.py`), so a bad release is out of your hands quickly: ship the fix as the next version, and yank on PyPI only if it is harmful (a yanked release is no longer offered). Verify step 6 before you walk away.
+
 - No copies of the source in other repositories. Pin the PyPI version in your requirements instead.
 - No PyPI API tokens. The trusted publisher configured for this repository is the only credential. If you hold a token for either package, say so and it gets revoked.
 - Every change is a pull request, however small. Review turnaround is same day.

{gravity_cli-0.5.6 → gravity_cli-0.6.0}/TEMPLATES.md

@@ -169,5 +169,5 @@ src/agent.py        exports `graph`
 .gitignore          .venv and caches. requirements.lock is NOT ignored: it ships.
 ```
 
-Note: templates declare `python: "3.13"`; the AgentCore base image is 3.12.
+Note: templates declare `python: "3.12"`, the version the platform runs.
 Set `runtime.python: "3.12"` in the manifest before `gravity push`.

{gravity_cli-0.5.6 → gravity_cli-0.6.0}/packages/gravity-schema/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gravity-schema"
-version = "0.5.6"
+version = "0.6.0"
 description = "Gravity agent manifest contract — models, validation, and JSON Schema export"
 readme = "README.md"
 license = "Apache-2.0"

{gravity_cli-0.5.6 → gravity_cli-0.6.0}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "gravity-cli"
-version = "0.5.6"
+version = "0.6.0"
 description = "gravity cli — init, run, and push python agents to the Gravity marketplace"
 readme = "README.md"
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
 requires-python = ">=3.12"
 dependencies = [
-    "gravity-schema==0.5.6",  # released in lockstep: always the same version as this package
+    "gravity-schema==0.6.0",  # released in lockstep: always the same version as this package
     "typer>=0.15.0",
     "httpx>=0.27.0",
     "rich>=13.9.0",

{gravity_cli-0.5.6 → gravity_cli-0.6.0}/src/gravity_cli/BUILDER_GUIDE.md

@@ -7,7 +7,8 @@ and a sign-in (`gravity login`, with your Google account).
 
 You write an ordinary Python agent with LangGraph and declare in `manifest.yaml` what it may
 touch. When we run it, Gravity gives it tools (Gmail, Linear, Slack…) and models through a
-gateway, and only the tools you declared. There is no Gravity SDK to learn.
+gateway, and only the tools you declared. The one Gravity package you may touch is `gravity`, which the
+platform preinstalls and which you need only to call approval-gated tools (§6.1).
 
 **Contents:** 1 how it works · 2 the folder · 3 the files (copy these) · 4 rules your code must
 follow · 5 output: formatting, formats and the gold standard · 6 add-ons: approvals, platform
@@ -26,7 +27,7 @@ you (gravity CLI)                       Gravity (on our machines)
 ─────────────────                       ──────────────────────────
 gravity init, change the files (§3)
 gravity validate                        the same checks the build runs
-gravity run / gravity dev         ──►   our real gateway and models, on the shared test accounts
+gravity run / gravity dev         ──►   our real gateway and models, on the accounts you connected
 gravity build, gravity push       ──►   validate, scan, build the image, start a runtime
 tell us it's ready                      we review it and list it on /app for users (§9, §10)
 ```
@@ -160,6 +161,11 @@ from langgraph.graph import END, StateGraph
 from pydantic import BaseModel, Field
 from summary import count_by_sender          # absolute import from src/
 
+try:
+    import gravity  # preinstalled on the platform, not on PyPI; absent in gravity run and in tests
+except ImportError:
+    gravity = None
+
 
 class Digest(BaseModel):
     headline: str = Field(description="the day's email in one sentence, from the given facts only")
@@ -189,16 +195,24 @@ def _payload(raw: Any) -> Any:
     return raw.get("data", raw) if isinstance(raw, dict) else raw
 
 
-async def graph():
-    # Read the three environment variables here, inside the function, never at import time.
-    token = os.environ["GRAVITY_RUN_TOKEN"]
-    model = ChatOpenAI(model="openai/gpt-6-luna", base_url=os.environ["GRAVITY_LLM_URL"], api_key=token)
+async def load_tools() -> dict:
+    """On the platform a tool under approvals.required_for must come from gravity.tools(): it pauses the
+    run until a person decides. Anywhere else the MCP client serves the same tools under the same names."""
+    if gravity:
+        return {t.name: t for t in await gravity.tools()}
     client = MultiServerMCPClient({"gravity": {
         "transport": "streamable_http",
         "url": os.environ["GRAVITY_GATEWAY_URL"],
-        "headers": {"Authorization": f"Bearer {token}"},
+        "headers": {"Authorization": f"Bearer {os.environ['GRAVITY_RUN_TOKEN']}"},
     }})
-    tools = {t.name: t for t in await client.get_tools()}  # only the tools in manifest.yaml
+    return {t.name: t for t in await client.get_tools()}
+
+
+async def graph():
+    # Read the three environment variables here, inside the function, never at import time.
+    token = os.environ["GRAVITY_RUN_TOKEN"]
+    model = ChatOpenAI(model="openai/gpt-6-luna", base_url=os.environ["GRAVITY_LLM_URL"], api_key=token)
+    tools = await load_tools()  # only the tools in manifest.yaml
 
     async def read(state: State):
         # Tool names use _ instead of . : gmail.read -> tools["gmail_read"]
@@ -285,7 +299,7 @@ If any of these is broken, the agent fails when we load or run it.
 | Every tool you call is in the manifest | `gmail.send` listed under `permissions.tools` | calling a tool you didn't list |
 | Accounts are reached only through tools, models only through `GRAVITY_LLM_URL` | `tools["gmail_read"]`, `ChatOpenAI(base_url=...)` | calling Gmail's API with your own credentials, your own API keys, `OPENAI_API_KEY` |
 | The final state sets `result` | `return {"result": {...}}` | a last node that returns nothing |
-| No Gravity imports | only your code and your dependencies | there's nothing to import anyway |
+| Gravity imports are optional | `import gravity` behind `try/except ImportError`, only to load approval-gated tools (§6.1) | listing `gravity` in `requirements.txt` (it is not on PyPI), or importing it unguarded |
 | Only declare `messages` in the state if the agent is a conversation | see §6.3 | adding it "just in case" (the agent is then run as a chat) |
 
 ## 5. Output: formatting, formats and the gold standard
@@ -438,6 +452,13 @@ the agent, that call is held until a human answers. If it isn't approved, the to
 containing `APPROVAL_REJECTED` or `APPROVAL_TIMEOUT` and does nothing, so **always have a
 fallback** (the example keeps a draft). A tool you gate must also be in `permissions.tools`.
 
+On the platform the run **pauses** for the decision (up to 7 days) instead of holding a connection, and
+that only works for tools loaded with `await gravity.tools()`: a gated call made through a plain MCP client
+fails there with `APPROVAL_REQUIRED`. The example's `load_tools()` does this, and falls back to the MCP client
+when `gravity` is not installed (`gravity run`, `gravity dev`, tests). After the decision the node that made
+the call runs again from its start, so keep the gated call last in its node. If you wrap the call in a broad
+`except`, re-raise `langgraph.errors.GraphBubbleUp` first (`except GraphBubbleUp: raise`), or the pause is swallowed.
+
 ### 6.2 Platform adapters: let the user choose where results go
 
 For agents whose output could go to different platforms (Gmail or Slack, WordPress or Webflow),
@@ -615,7 +636,7 @@ return {"result": result, "memory": {"seen": sorted(seen | delivered)[-1000:]}}
 
 Your agent can be for any field: sales, marketing, finance, support, engineering, operations,
 anything. **The table below is today's starting set, not the limit.** If your agent needs a tool
-that isn't here, run `gravity tools <app>` first: the gateway serves about 1,100 more tools for the
+that isn't here, run `gravity tools <app>` first: the gateway serves more than 1,300 more tools for the
 same apps. If it still isn't there, ask for it as in §7.1.
 
 | App | Tools |
@@ -737,13 +758,13 @@ see, locally or hosted:
 | Message | It means | Fix |
 |---|---|---|
 | `TOOL_NOT_DECLARED` | Your code called a tool that isn't in the manifest | Add it to `permissions.tools` (or the adapter's list), or stop calling it |
-| `NEEDS_RECONNECT` | Our shared test account for that app isn't connected (or its sign-in lapsed) | Tell us and we reconnect it. `gravity connect <app>` refuses on the shared account on purpose: local runs share one test account until per-builder accounts ship, so anything you connected would be used by every builder's runs |
+| `NEEDS_RECONNECT` | The account for that app isn't connected, or its sign-in lapsed | Locally: `gravity connect <app>` connects your own account (a `gravity login` run uses the accounts you connected). Only if you run with `GRAVITY_DEV_TOKEN` are you on the shared test account, where `gravity connect` refuses on purpose and you tell us to reconnect it. Hosted, the person running the agent connects it |
 | `TOOL_NOT_FOUND` | A tool in `manifest.yaml` isn't in the catalog | Check the spelling with `gravity tools`. For a new one, ask for it (§7.1) |
 | `APPROVAL_REQUIRED` | An imported write tool has no approval | List it under `approvals.required_for`, with a fallback (§6.1) |
 | `UNDECLARED_TOOL_CALL` | Your code names a write tool the manifest doesn't grant | Declare it (and gate it), or remove the call |
 | `TOOL_UNAVAILABLE` | That tool isn't available yet | Check the spelling against §7, or wait until we've added it (§7.1) |
 | `APPROVAL_REJECTED` / `APPROVAL_TIMEOUT` | A gated call wasn't approved | Expected; your fallback should have run |
-| "the final state has no result" | Your last node didn't set `result` | Return `{"result": ...}` |
+| "finished without a result" (`gravity run`), or a `null` result on the platform | Your last node didn't set `result` | Return `{"result": ...}` |
 | "could not load the agent" | An import error, a relative import, or building the graph at import | Follow §4 |
 | Lockfile doesn't compile | A dependency has no Linux ARM64 wheel | Choose another version or package |
 

gravity_cli-0.6.0/src/gravity_cli/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+Shown by `gravity update` and `gravity changelog`, and after an update. Each release is `## X.Y.Z - date`,
+then one bullet per change: `- new|improved|fixed: A one-line headline. The detail behind it.`
+Write it for a builder, not for a maintainer. `tests/test_changelog.py` fails a release that has no entry.
+
+## 0.6.0 - 2026-10-22
+
+- new: Gravity CLI keeps itself up to date. Once every six hours a command checks PyPI; when there is a newer release it says so, updates, and runs your command again as the new version. GRAVITY_AUTO_UPDATE=0 turns it off.
+- new: gravity update and gravity changelog. Update on demand (--check only looks), and read what changed in any release.
+- new: Gravity.agent.md and problem-to-agent.md appear in the folder you run gravity in. They tell your coding agent how Gravity runs agents, the manifest, the tools and the build method, and are rewritten on every update. A file you edited is left alone, and your own agent.md is never touched.
+- new: gravity docs writes or refreshes those two files on demand; --force replaces ones you edited.
+- improved: gravity on its own is now a short home screen. It shows your version, the agent in this folder, whether you are signed in and any update, the next step for where you are, and every command on one line per group. gravity -h still lists them all with descriptions.
+
+## 0.5.6 - 2026-10-15
+
+- new: Firecrawl tools. firecrawl.search and firecrawl.scrape read pages that refuse plain HTTP clients, and web.render is the plain fallback for pages web.fetch returns empty. They run on your own connected Firecrawl account.
+
+## 0.5.5 - 2026-10-13
+
+- new: manifest.yaml takes an optional display: hint. It tells the page how a run's result shows (document, report, table, chart, code or files). It is a hint, never a rule, so an unknown value never fails a push.
+
+## 0.5.4 - 2026-10-10
+
+- improved: gravity agents shows the review. A REVIEW column (not submitted, submitted, approved, rejected), each message from the Gravity team with its decision and what to do next, and why an agent was turned off.
+
+## 0.5.3 - 2026-10-10
+
+- new: WhatsApp in the tool catalog. 51 tools with Composio-managed sign-in.
+- new: gravity dev shows images in outputs, from image data URLs.
+- improved: the builder guide explains NEEDS_RECONNECT on the shared test account: ask Gravity, do not connect your own.
+
+## 0.5.2 - 2026-10-10
+
+- new: Jira, Confluence and Notion in the tool catalog. 209 more tools, all with Composio-managed sign-in; imported writes need approvals.required_for.
+- new: gravity run keeps get_store() locally in .gravity/store.json, so a monitor's history can be tried before it ships.
+- improved: gravity starts faster.

{gravity_cli-0.5.6 → gravity_cli-0.6.0}/src/gravity_cli/api.py

@@ -18,6 +18,14 @@ CHECK_URL = "Check GRAVITY_API_URL in ~/.gravity/.env, or api_url in ~/.gravity/
 IN_THE_WAY = "Check GRAVITY_API_URL, or whether a proxy or login page is in the way."
 
 
+def _where_the_address_came_from() -> str:
+    """Which setting chose the address and what it is hiding: a stale localhost line in .env beats the saved one."""
+    shadowed = config.api_url_shadowed()
+    if not shadowed:
+        return f"The address comes from {config.api_url_source()}. {CHECK_URL}"
+    return f"The address comes from {config.api_url_source()}, which overrides {shadowed} saved in config.json. Remove that setting to use the saved one, or point at another with gravity --api-url."
+
+
 def _token() -> str:
     # GRAVITY_API_TOKEN (the control plane's dev token) wins over a stored session.
     token = os.environ.get("GRAVITY_API_TOKEN", "").strip()
@@ -40,7 +48,7 @@ def _request(
         with httpx.Client(base_url=config.api_url(), timeout=timeout, headers=sent) as client:
             resp = client.request(method, path, **kw)
     except httpx.TransportError as e:
-        raise Problem(f"Can't reach Gravity at {config.api_url()}", str(e), CHECK_URL) from e
+        raise Problem(f"Can't reach Gravity at {config.api_url()}", str(e), _where_the_address_came_from()) from e
     if resp.status_code == 401 and auth:
         if os.environ.get("GRAVITY_API_TOKEN", "").strip():
             raise Problem("Gravity refused GRAVITY_API_TOKEN", fix="Fix it in ~/.gravity/.env, or remove it and run gravity login.")

gravity_cli-0.6.0/src/gravity_cli/changelog.py

@@ -0,0 +1,55 @@
+"""CHANGELOG.md, shipped inside the package: what each release changed, in the words a builder reads.
+
+A release is `## X.Y.Z - date`, followed by bullets `- new|improved|fixed: A sentence. More detail.`
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+CHANGELOG = Path(__file__).parent / "CHANGELOG.md"
+TAGS = ("new", "improved", "fixed")
+_HEADING = re.compile(r"^##\s+(\d+(?:\.\d+)*)\s*(?:[-–—]\s*(.+))?$")
+_BULLET = re.compile(rf"^-\s+({'|'.join(TAGS)}):\s+(.+)$", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class Change:
+    tag: str
+    text: str
+
+
+@dataclass(frozen=True)
+class Release:
+    version: str
+    date: str
+    changes: tuple[Change, ...]
+
+
+def version_key(version: str) -> tuple[int, ...] | None:
+    return tuple(int(part) for part in version.split(".")) if re.fullmatch(r"\d+(\.\d+)*", version or "") else None
+
+
+def parse(text: str) -> list[Release]:
+    """Newest first, in the order the file lists them."""
+    releases: list[tuple[str, str, list[Change]]] = []
+    for line in text.splitlines():
+        if heading := _HEADING.match(line.strip()):
+            releases.append((heading[1], (heading[2] or "").strip(), []))
+        elif releases and (bullet := _BULLET.match(line.strip())):
+            releases[-1][2].append(Change(bullet[1].lower(), bullet[2].strip()))
+    return [Release(version, date, tuple(changes)) for version, date, changes in releases]
+
+
+def releases() -> list[Release]:
+    return parse(CHANGELOG.read_text(encoding="utf-8"))
+
+
+def since(previous: str, current: str) -> list[Release]:
+    """Releases after `previous`, up to and including `current`, newest first."""
+    low, high = version_key(previous), version_key(current)
+    if low is None or high is None:
+        return []
+    return [r for r in releases() if (key := version_key(r.version)) and low < key <= high]