pagegraph 0.6.1 → 0.8.0

package/README.md

@@ -34,13 +34,14 @@ bun add -D lighthouse   # only for `pagegraph audit` performance evidence
 | `pagegraph/audit`  | Audit services, scanner protocol, rules, and report schemas                                    | `effect`                                    |
 | `pagegraph` bin                   | CLI over the same graph                                                                        | bundled — runs on Bun                        |
 
-The core and React entries have **zero runtime dependencies** — everything above is a
-peer, and only the entries you import need theirs installed.
+The core and React import graphs have **zero runtime dependencies** — everything they use is a
+peer, and only the entries you import need those peers loaded.
 
-The CLI **bundles Effect and the TypeSafe provider**, so it needs no Effect peers and does not
-depend on the app's Effect RC; it runs on [Bun](https://bun.sh) (`bunx pagegraph`). `vite` stays a
-peer — the graph commands load your app through Vite at runtime — and `lighthouse` is only needed by
-`pagegraph audit`. Importing `pagegraph/audit` programmatically still needs `effect`.
+The CLI **bundles PageGraph's Effect and TypeSafe provider runtime**, so it does not depend on the
+app's Effect RC; it runs on [Bun](https://bun.sh) (`bunx pagegraph`). Agentic workflows load the
+OpenCode SDK and its private Effect runtime only when invoked. `vite` stays a peer — graph commands
+load your app through Vite at runtime — and `lighthouse` is only needed by `pagegraph audit`.
+Importing `pagegraph/audit` programmatically still needs `effect`.
 
 ## Quick start
 
@@ -205,6 +206,89 @@ Preview hosts (`indexable: false`) drop `contentSignal` and `directives`;
 pagegraph check
 ```
 
+## Agentic workflows
+
+PageGraph can combine the deterministic route graph with a project-owned embedded OpenCode agent,
+live tools exposed by an Executor plugin, and Jev decisions. Scaffold the OpenCode preset once:
+
+```bash
+pagegraph init
+```
+
+The generated `.pagegraph/opencode` directory contains one `seo` agent and customizable `content`,
+`technical`, and `authority` skills. Add your Executor plugin to its `opencode.jsonc`; OpenCode and
+the plugin own model and Executor authentication. PageGraph does not copy credentials or assume
+fixed provider-tool addresses.
+
+Enable workflows in `seo.config.ts`:
+
+```ts
+export default defineSeoConfig({
+  // origin, disallow, and loadGraph as above
+  workflows: {
+    opencode: {
+      configDirectory: ".pagegraph/opencode",
+      defaultModel: "openrouter/example/model",
+      models: {
+        "research.keywords": "openrouter/example/research-model",
+      },
+    },
+    context: {
+      files: ["AGENTS.md"],
+      byWorkflow: {
+        "research.keywords": ["docs/seo/measurement.md"],
+      },
+    },
+    runsDirectory: ".pagegraph/runs",
+  },
+});
+```
+
+Run a page-backed workflow:
+
+```bash
+pagegraph research keywords \
+  --query "transactional email api" \
+  --market us \
+  --language en
+```
+
+Every workflow starts from the selected graph and context files, asks the SEO agent to search
+Executor's live catalog and compose suitable tools, then evaluates its structured observations with
+Jev. Tool paths are discovered at runtime; the generated skills contain editable starter recipes,
+not a fixed integration list.
+
+| Command | Result |
+| --- | --- |
+| `research keywords` | Query demand, intent, and page ownership opportunities |
+| `research competitors` | Competitor topics, pages, and positioning evidence |
+| `research authority` | Qualified editorial, directory, partner, and community opportunities |
+| `analyze serp` | Search-result intent and page-shape fit |
+| `analyze content` | Substance, answer quality, and intent overlap |
+| `analyze ai-search` | Citation readiness and answer-engine coverage |
+| `plan architecture` | A page-backed information-architecture plan |
+| `improve content` | Evidence-backed source copy edits |
+| `improve metadata` | Title and description edits at the owning source |
+| `improve schema` | Structured-data edits justified by visible content |
+| `improve links` | Contextual internal-link edits from graph and page evidence |
+
+The common selectors are repeatable `--page`, `--query`, and `--kind`, plus `--limit`, `--market`,
+`--language`, `--refresh`, `--model`, `--opencode-config`, and `--out`. Relevant workflows also
+accept `--competitor`, `--domain`, or `--device desktop|mobile`. Workflows are noninteractive and
+fail immediately if the agent asks a question or requests permission.
+
+The four `improve` workflows write source files by default and require a clean Git tree. Use
+`--dry-run` to keep repository edit and shell tools disabled, or `--allow-dirty` when you explicitly
+want the agent to edit alongside existing changes. PageGraph leaves every diff uncommitted and
+records modified, added, and deleted files after the workflow finishes.
+
+Each run writes `.pagegraph/runs/<run-id>/run.json` and `summary.md`. The JSON retains the
+deterministic graph, context, complete OpenCode session export, Executor tool evidence, Jev question
+definitions and answers, Git provenance, changed files, and model provenance. Keep this directory
+ignored: provider output can be large or account-specific. Workflows fail when the configured model,
+active Executor plugin, catalog search plus discovered tool call, or `TYPESAFE_API_KEY` for Jev is
+unavailable.
+
 ## Typed paths
 
 Augment `Register` (the same pattern TanStack Router uses) and `related` /
@@ -308,7 +392,8 @@ pagegraph links verify <url>    # crawl served HTML: depth, orphans, declared-vs
 pagegraph links verify <url> --assert-coverage  # also assert seo.config.ts coverage on served anchors
 pagegraph links verify <url> --emit-rendered <file>  # save the rendered edge set
 pagegraph links candidates      # propose contextual links from the declared graph
-pagegraph links decide <file>   # answer typed link questions with Jev (TYPESAFE_API_KEY)
+pagegraph research keywords --query "email api"  # combine graph, Executor, and Jev evidence
+pagegraph improve metadata --page /pricing       # apply a clean-tree source improvement
 pagegraph sitemap               # print sitemap.xml
 pagegraph robots                # print robots.txt
 ```
@@ -394,36 +479,18 @@ Pairs already declared as a `related` edge are excluded, and `--rendered` accept
 a JSON dump of already-served anchors (`[{ from, to }]` or `{ edges: [...] }`) to
 exclude those too.
 
-The output is a reviewable plan: human text by default, versioned JSON with
-`--json`. Nothing is applied. `--limit` and `--cluster` bound the plan, and
-`--decide` optionally hands the candidates to Jev for a recommendation and
-confidence per pair (requires `TYPESAFE_API_KEY`):
+The output is a deterministic, reviewable plan: human text by default and
+versioned JSON with `--json`. Nothing is applied; `--limit` and `--cluster`
+bound the plan. Use `pagegraph improve links` when you want Executor evidence,
+Jev evaluation, and source edits:
 
 ```bash
 pagegraph links candidates
 pagegraph links candidates --cluster blog --limit 20
 pagegraph links candidates --rendered rendered.json --json | jq
-pagegraph links candidates --decide
+pagegraph improve links --page "/docs/**"
 ```
 
-### Decide with Jev
-
-`pagegraph links decide` answers two typed questions per candidate — *does the source have a genuine
-reason to link to the destination?* and *is descriptive anchor text already in the copy?* — and
-routes anything inside the confidence band `(1−t, t)` to a `review` bucket instead of auto-applying.
-
-```bash
-pagegraph links decide candidates.json --threshold 0.9
-pagegraph links decide candidates.json --threshold 0.9 --json | jq
-cat candidates.json | pagegraph links decide
-```
-
-Decisions run through [Jev](https://typesafe.ai) via `@effect/ai-typesafe` (model `jev-latest`),
-bundled into the CLI. The API key is read from the **`TYPESAFE_API_KEY` environment variable** — it
-is deliberately not a `seo.config.ts` field, so keys never live in the repo; `seo.config.ts` carries
-non-secret decision settings only. Without a key the command exits 1 with a clear message and an
-empty stdout.
-
 ### Contextual-link coverage
 
 Declare a contextual-link coverage policy in `seo.config.ts` (a `coverage` array