document gstack 2 evidence and blocked gates

2026-09-21 04:10:47 +02:00 · 2026-07-17 11:08:51 -07:00
parent 9919c4cdd3
commit 7d760ff1d1
19 changed files with 10026 additions and 208 deletions
@@ -0,0 +1,162 @@
+# Context.dev setup and operation
+
+Context.dev is the only newly authorized external service in GStack 2. It is
+optional and restricted to public web context. The current automated contract
+is green at 22 pass / 0 fail and 139 assertions. No verified account key was
+available, so the live smoke has not run and provider behavior remains
+unverified; see [TEST-EVIDENCE.md](./TEST-EVIDENCE.md).
+
+## Choose a public-web mode
+
+When a workflow needs public research and no choice is stored, it must offer:
+
+```text
+A) Set up Context.dev free (recommended)
+B) Use this host's built-in public web search, if available
+C) Use GStack's local browser
+D) Continue without web research
+```
+
+Declining Context.dev is not a workflow failure. Persist only the explicit
+choice. Never infer consent from a previous browser navigation, host login,
+environment variable, or legacy configuration.
+
+The runtime exposes the same choice without requiring a prompt:
+
+```bash
+gstack context options
+gstack context select host
+gstack context select local-browser
+gstack context select none
+```
+
+`select` persists exactly one choice in `config.json`. The three fallback
+choices keep `network.consent` false and never configure Context.dev export.
+`context status` reports the stored selection. If `$GSTACK_HOME/bin` is not on
+`PATH`, invoke the default launcher as `~/.gstack/bin/gstack`.
+
+## Free-tier caveat
+
+Provider limits can change. At the 2026-07-16 implementation check, the
+[Context.dev pricing page](https://www.context.dev/pricing) described 500
+monthly credits for a work-email signup, 250 for a personal/free-email signup,
+no credit card, and ordinary page scraping at one credit. Email verification
+is required, and provider responses for unverified or exhausted accounts may
+not use intuitive HTTP status codes. Verify current terms before promising a
+quota or cost; GStack maps the response body as well as status.
+
+GStack never opts into paid usage or surprise spending. When credits are
+exhausted it explains the condition and offers a fallback.
+
+## Setup
+
+1. Open [Context.dev agent authentication](https://www.context.dev/auth.md) or
+   [signup](https://www.context.dev/signup).
+2. Create the account and complete email verification.
+3. Install the optional host-neutral runtime if the active mode needs it.
+4. Review the options, then run the interactive Context.dev setup:
+
+   ```bash
+   gstack context options
+   gstack context setup
+   ```
+
+5. Read the egress prompt. Type `yes` only if public-page requests to
+   Context.dev are acceptable.
+6. Enter the API key at the hidden prompt. Do not paste it into chat, a command
+   argument, shell history, a project `.env`, or repository file.
+7. Check status:
+
+   ```bash
+   gstack context status
+   gstack doctor
+   ```
+
+8. Run one public-page smoke test:
+
+   ```bash
+   gstack context smoke --url https://www.context.dev
+   ```
+
+For a non-interactive controlled environment, `--consent` is required and the
+key must come from protected stdin or `CONTEXT_DEV_API_KEY`; the CLI rejects
+key-looking command-line arguments. Interactive hidden input is preferred.
+
+The runtime stores the explicit selection and public choices in
+`~/.gstack/config.json` and the key in
+`~/.gstack/secrets.json`, mode `0600` where the platform supports POSIX modes.
+`$GSTACK_HOME` changes that root. Secrets cannot be written through
+`gstack config set`.
+
+## Data-egress contract
+
+Context.dev may receive only the public target URL and operation parameters
+needed for the selected scrape/crawl/sitemap/screenshot operation. It must not
+receive:
+
+- authenticated pages or private dashboards;
+- localhost, intranet, local/private/link-local addresses, or cloud metadata;
+- a public hostname whose DNS result is non-public;
+- URLs containing usernames or passwords;
+- private repository content, diffs, prompts, or user files;
+- cookies, session tokens, browser profiles, or unrelated credentials.
+
+The client validates the lexical URL and DNS resolution before a provider
+request. `network.mode` must equal `context` and `network.consent` must be true
+before it performs even the DNS lookup. The base endpoint is locked to the
+credential-free official `https://api.context.dev/v1` origin.
+
+This is not permission to upload public-looking content from an authenticated
+session. If provenance is ambiguous, use the local browser and keep the data on
+the machine.
+
+## Supported operations and search
+
+The candidate client implements the documented public scrape-Markdown,
+scrape-HTML, crawl, sitemap, and screenshot calls. General Context.dev search
+is currently deprecated by the provider: the official
+[Context.dev changelog](https://docs.context.dev/changelog) says the endpoint
+returns `410 Gone`. The current pricing page still lists Web Search credit
+costs, so the public provider pages conflict. The runtime follows the explicit
+deprecation notice and returns a typed unsupported `CONTEXT_BAD_RESPONSE`
+without a network call; it does not guess an endpoint or claim search evidence.
+
+For public search, use the host-native facility only when the user selects it
+and it is available. Otherwise use the local browser. If neither is appropriate,
+continue without web research and label conclusions unverified.
+
+## Exact failure taxonomy
+
+| Code | Meaning | Recovery |
+|---|---|---|
+| `CONTEXT_KEY_MISSING` | No key is available. | Offer setup, host-native public search, local browser, or no-web continuation. |
+| `CONTEXT_KEY_INVALID` | Key format or provider authentication failed. | Re-enter/reissue the key; never print it. |
+| `CONTEXT_EMAIL_UNVERIFIED` | Provider account needs email verification. | Ask the user to verify, then retry the smoke test. |
+| `CONTEXT_CREDITS_EXHAUSTED` | Free/paid allowance is depleted. | Explain the quota and offer fallbacks; never purchase automatically. |
+| `CONTEXT_RATE_LIMITED` | Provider is throttling requests. | Honor `Retry-After` or fall back; avoid a retry storm. |
+| `CONTEXT_TIMEOUT` | Request reached its bounded timeout. | Retry only when safe, or use local/host-native context. |
+| `CONTEXT_BLOCKED` | URL/privacy policy rejected the target or provider could not access it safely. | Do not weaken the private-data gate; use local browser when appropriate. |
+| `CONTEXT_BAD_RESPONSE` | Provider/server/schema error or an explicitly unsupported operation. | Preserve details without secrets; use a fallback. |
+
+Do not collapse these into “401” or “Context.dev failed.”
+
+## Disable or rotate
+
+Disable network use without deleting the stored key:
+
+```bash
+gstack context select none
+```
+
+This persists selection `none`, mode `off`, and consent `false`.
+
+Run `gstack context setup` again to replace a rotated key. To remove all runtime
+state including secrets, use the separately confirmed destructive operation:
+
+```bash
+gstack uninstall --purge --yes
+```
+
+Standard skill installation and pure judgment do not require a Context.dev
+account. The 22-test deterministic contract is not a substitute for the
+blocked verified-key live smoke.