feat: Add UIGraph configuration and diagram files

.uigraph.yaml

@@ -0,0 +1,29 @@
+version: 1
+
+service:
+  name: UIGraph
+  category: CLI
+  description: CLI and local viewer that show a project's services, APIs, dependencies and diagrams, and run Lens pull request reviews.
+  repository:
+    provider: github
+    url: https://github.com/uigraph-oss/uigraph
+  ownership:
+    team: uigraph-oss
+
+architectureDiagrams:
+  - name: System Context
+    path: .uigraph/diagrams/system-context/system-context.mmd
+    contextPath: .uigraph/diagrams/system-context/context.json
+  - name: Lens Review Run
+    path: .uigraph/diagrams/lens-review-run/lens-review-run.mmd
+    contextPath: .uigraph/diagrams/lens-review-run/context.json
+
+docs:
+  - name: README
+    path: README.md
+    fileType: markdown
+    description: Install, quick start, commands and Lens
+  - name: Contributing Guide
+    path: CONTRIBUTING.md
+    fileType: markdown
+    description: Development setup and review expectations

.uigraph/AGENTS.md

@@ -0,0 +1,26 @@
+# UIGraph artifacts
+
+This repository describes its architecture in UIGraph artifacts: `.uigraph.yaml`, `.uigraph/services/*.yaml`, and the files under `.uigraph/`. The UIGraph viewer and Lens pull request reviews read them, so keep them true to the code.
+
+## When to update
+
+Update artifacts only when your change does one of these. For any other change, do nothing here.
+
+| Your change | Update |
+|---|---|
+| Adds, removes, or changes an HTTP, GraphQL, or gRPC endpoint, or its request or response fields | The spec listed under `apis` |
+| Adds or changes a migration, ORM model, or DDL | The schema listed under `databases`, and each entry under `queries` that uses the changed tables |
+| Starts or stops calling another service, datastore, or third-party API | `dependencies` in that service's config |
+| Changes a flow that a diagram shows | That diagram's `.mmd` file |
+| Adds a deployable service | A new config at `.uigraph/services/<service-name>.yaml` |
+| Makes a doc listed under `docs` wrong | That doc |
+
+## How to update
+
+1. Read `.uigraph.yaml`, and `.uigraph/services/*.yaml` when the change is in another service. They list every artifact and its file. Open only the files your change affects, and do not explore the rest of `.uigraph/`.
+2. Change only what your code change made wrong. Keep the existing structure, names, and order.
+3. Base every change on code you read. Never invent endpoints, dependencies, tables, or flows.
+4. In diagrams, never write `style`, `classDef`, `class`, `linkStyle`, or colors.
+5. Run `npx --yes uigraph sync` and fix every problem it reports.
+
+When you are not sure whether your change affects an artifact, leave the artifact as it is and say so in your summary. Lens flags out-of-date diagrams and docs on each pull request.

.uigraph/diagrams/lens-review-run/context.json

@@ -0,0 +1,17 @@
+{
+  "nodes": {
+    "cmd": { "name": "uigraph lens" },
+    "resolve": { "name": "Resolve PR or branches" },
+    "start_viewer": { "name": "Start viewer if needed" },
+    "handler": { "name": "handleLensRequest (server.ts)" },
+    "start_run": { "name": "startLensRun (lens.ts)" },
+    "source": { "type": "shape", "shape": "diamond", "name": "Review source" },
+    "token": { "name": "Resolve GitHub token (GITHUB_TOKEN, GH_TOKEN, gh)" },
+    "github": { "name": "GitHub" },
+    "local_git": { "name": "readLocalReview via git" },
+    "analyze": { "name": "analyzeReview with chosen agent" },
+    "subscribers": { "name": "Run subscribers" },
+    "lens_data": { "type": "shape", "shape": "document", "name": "~/.uigraph/lens/runs" },
+    "lens_page": { "name": "Viewer Lens page" }
+  }
+}

.uigraph/diagrams/lens-review-run/lens-review-run.mmd

@@ -0,0 +1,15 @@
+flowchart TD
+  cmd[uigraph lens] --> resolve[Resolve PR or branches]
+  resolve --> start_viewer[Start viewer if needed]
+  start_viewer -->|POST api lens runs| handler[handleLensRequest]
+  handler --> start_run[startLensRun]
+  start_run --> source{Review source}
+  source -->|github| token[Resolve GitHub token]
+  token -->|fetchReview| github[GitHub]
+  source -->|local| local_git[readLocalReview via git]
+  github --> analyze[analyzeReview with agent]
+  local_git --> analyze
+  analyze -->|stage updates| subscribers[Run subscribers]
+  analyze -->|saved runs| lens_data[~/.uigraph/lens]
+  subscribers --> lens_page[Viewer Lens page]
+  start_run -->|runId| cmd