From accfad22ad8546fc825436259712a4dd01154990 Mon Sep 17 00:00:00 2001
From: apstndb <803393+apstndb@users.noreply.github.com>
Date: Tue, 19 May 2026 01:30:38 +0900
Subject: [PATCH 1/3] Add repository agent guidance

---
 .gemini/config.yaml |  2 ++
 .gitignore          |  6 ++++
 AGENTS.md           | 88 +++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md           |  1 +
 4 files changed, 97 insertions(+)
 create mode 100644 .gemini/config.yaml
 create mode 100644 .gitignore
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/.gemini/config.yaml b/.gemini/config.yaml
new file mode 100644
index 0000000..99feafa
--- /dev/null
+++ b/.gemini/config.yaml
@@ -0,0 +1,2 @@
+code_review:
+  comment_severity_threshold: HIGH
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..1ed3f72
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,6 @@
+# Local scratch space for generated artifacts and temporary notes.
+.tmp/
+
+# Local editor and OS metadata.
+.DS_Store
+.idea/
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..727c456
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,88 @@
+# AGENTS.md
+
+This file provides guidance to Codex and other coding agents when working with code in this repository.
+
+## Project Overview
+
+spannerplanviz is a Cloud Spanner Query Plan Visualizer that converts Spanner query plans into visual diagrams using Graphviz and Mermaid.js. The tool reads JSON/YAML input containing Spanner query plans and generates visual output in various formats (SVG, PNG, DOT, Mermaid).
+
+## Architecture
+
+### Core Components
+
+- **main.go**: Entry point that parses CLI options, reads input, and orchestrates visualization
+- **option/options.go**: Defines CLI flags and options for controlling output format and content
+- **visualize/**: Core visualization logic
+  - **visualize.go**: Main rendering coordinator, handles both Graphviz and Mermaid output paths
+  - **mermaid.go**: Mermaid.js-specific rendering logic with structured configuration
+  - **build_tree.go**: Converts Spanner plan nodes into internal tree structure
+  - **util.go**: Utility functions for formatting and text processing
+
+### Dependencies
+
+- **github.com/apstndb/spannerplan**: External library for parsing Spanner query plans
+- **github.com/goccy/go-graphviz**: Graphviz rendering engine
+- **cloud.google.com/go/spanner**: Google Cloud Spanner client library for protobuf definitions
+- **github.com/jessevdk/go-flags**: CLI argument parsing
+
+### Input/Output Flow
+
+1. Input: JSON/YAML containing QueryPlan, ResultSetStats, or ResultSet from Spanner
+2. Parse using spannerplan.ExtractQueryPlan()
+3. Build internal tree structure via buildTree()
+4. Render output based on --type flag (svg/png/dot/mermaid)
+
+## Development Commands
+
+### Testing
+
+```bash
+make test
+# Or directly:
+go test -v ./...
+
+# Test with sample data:
+go run . --type=mermaid --full < visualize/testdata/dca_profile.json
+go run . --type=svg --full --output=test.svg < visualize/testdata/dca_profile.json
+```
+
+### Building
+
+```bash
+go build -o spannerplanviz .
+```
+
+### Running
+
+```bash
+# Basic usage - reads from stdin, outputs to stdout
+echo '{"queryPlan": {...}}' | go run . --type=svg
+
+# With file input/output
+go run . --input=plan.json --output=plan.svg --type=svg --full
+```
+
+### CLI Options
+
+- `--type`: Output format (svg, png, dot, mermaid)
+- `--full`: Enable all metadata options (execution-stats, metadata, etc.)
+- `--output`: Output file path
+- `--show-query`: Include query text in visualization
+- `--show-query-stats`: Include query statistics
+
+### Test Data
+
+Sample files in `visualize/testdata/` for testing:
+
+- `dca_profile.json`: Complex distributed cross apply query with profile data
+- `various_characters_profile.json`: Tests special character handling
+- `*.golden.mermaid`: Expected Mermaid output for regression testing
+
+## Code Conventions
+
+- Standard Go formatting with gofmt
+- Use struct methods for node operations (GetName(), HTML(), MermaidLabel())
+- Error wrapping with fmt.Errorf() for context
+- Defer cleanup for resources (files, graphviz objects)
+- Use cgraph.EdgeStyle constants for edge styling
+- Mermaid output uses structured JSON configuration for theming
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md

From 870f88a4b90dc6b8b4ce36894874b3d715a0562f Mon Sep 17 00:00:00 2001
From: apstndb <803393+apstndb@users.noreply.github.com>
Date: Tue, 19 May 2026 01:45:49 +0900
Subject: [PATCH 2/3] Address review feedback

---
 .gitignore           | 3 +++
 AGENTS.md            | 4 ++--
 visualize/mermaid.go | 4 ++--
 3 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/.gitignore b/.gitignore
index 1ed3f72..dbda47a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,6 @@
 # Local editor and OS metadata.
 .DS_Store
 .idea/
+
+# Local Go build output.
+spannerplanviz
diff --git a/AGENTS.md b/AGENTS.md
index 727c456..a2ecbf8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -81,8 +81,8 @@ Sample files in `visualize/testdata/` for testing:
 ## Code Conventions
 
 - Standard Go formatting with gofmt
-- Use struct methods for node operations (GetName(), HTML(), MermaidLabel())
-- Error wrapping with fmt.Errorf() for context
+- Follow existing tree node helper methods for node operations, such as GetName(), HTML(), and MermaidLabel()
+- Wrap errors with fmt.Errorf() and %w when preserving the underlying cause
 - Defer cleanup for resources (files, graphviz objects)
 - Use cgraph.EdgeStyle constants for edge styling
 - Mermaid output uses structured JSON configuration for theming
diff --git a/visualize/mermaid.go b/visualize/mermaid.go
index cc2eeca..14929fb 100644
--- a/visualize/mermaid.go
+++ b/visualize/mermaid.go
@@ -53,8 +53,8 @@ func renderMermaid(rootNode *treeNode, writer io.Writer, qp *spannerplan.QueryPl
 		// Use the new MermaidLabel method
 		finalLabel := node.MermaidLabel(qp, param, rowType) // Pass qp, param, rowType
 
-		sb.WriteString(fmt.Sprintf("    %s[\"%s\"]\n", nodeName, finalLabel))
-		sb.WriteString(fmt.Sprintf("    style %s text-align:left;\n", nodeName))
+		fmt.Fprintf(&sb, "    %s[\"%s\"]\n", nodeName, finalLabel)
+		fmt.Fprintf(&sb, "    style %s text-align:left;\n", nodeName)
 
 		// Edges
 		for _, edgeLink := range node.Children {

From d304dd079813c8afd43caefb18cf34de0b0edc60 Mon Sep 17 00:00:00 2001
From: apstndb <803393+apstndb@users.noreply.github.com>
Date: Tue, 19 May 2026 01:54:31 +0900
Subject: [PATCH 3/3] Refine agent guidance

---
 AGENTS.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index a2ecbf8..dc51da6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
 # AGENTS.md
 
-This file provides guidance to Codex and other coding agents when working with code in this repository.
+This file provides guidance to AI coding agents when working with code in this repository.
 
 ## Project Overview
 
@@ -15,7 +15,7 @@ spannerplanviz is a Cloud Spanner Query Plan Visualizer that converts Spanner qu
 - **visualize/**: Core visualization logic
   - **visualize.go**: Main rendering coordinator, handles both Graphviz and Mermaid output paths
   - **mermaid.go**: Mermaid.js-specific rendering logic with structured configuration
-  - **build_tree.go**: Converts Spanner plan nodes into internal tree structure
+  - **build_tree.go**: Converts Spanner plan nodes into internal tree structure and defines node formatting logic for HTML and Mermaid labels
   - **util.go**: Utility functions for formatting and text processing
 
 ### Dependencies