Update steering docs with schema storage, related issues, and project references

.kiro/steering/project-management.md

@@ -0,0 +1,68 @@
+---
+inclusion: always
+---
+
+# Project Management
+
+## General
+
+- Use the `gh` CLI for all GitHub operations when possible
+- Never delete or change the status of issues or pull requests unless explicitly
+  requested
+
+## Issues
+
+- Always assign an issue type when creating issues: `Task`, `Bug`, `Feature`,
+  `Epic`, or `Spike`
+- Use context from the codebase or the web to fill in additional detail when
+  creating issues
+- Only apply labels from the existing set; do not create new labels
+- Do not add or remove labels unless explicitly requested
+
+## Sub-Issues
+
+Create a sub-issue (child) under a parent issue:
+
+```bash
+PARENT_ID=$(gh issue view <parent-number> --json id --jq '.id')
+CHILD_ID=$(gh issue view <child-number> --json id --jq '.id')
+gh api graphql \
+  -H "GraphQL-Features: sub_issues" \
+  -f query="mutation { addSubIssue(input: { issueId: \"$PARENT_ID\", subIssueId: \"$CHILD_ID\" }) { issue { title } subIssue { title } } }"
+```
+
+Note: `gh issue create` does not support `--parent`. Create the issue first,
+then link it via the GraphQL API as shown above.
+
+## Related Issues
+
+When an issue or PR relates to another issue or PR, add a "Related Issues"
+section with a list of linked items. Always use a list format, even for a single
+item, because GitHub expands the reference number into the referenced item's
+title (e.g., `- Fixes #123` renders as "Fixes some bug #123").
+
+Prefix each item with a brief relationship descriptor such as:
+
+- `Fixes` or `Resolves` — closes the referenced issue
+- `Part of` — contributes to a larger effort
+- `Parent` — the parent issue or epic
+- `Duplicate` — duplicates another issue
+- Other brief descriptors as appropriate
+
+Example:
+
+```markdown
+## Related Issues
+
+- Fixes #123
+- Part of #456
+```
+
+## Pull Requests
+
+- Always publish pull requests as drafts
+- Follow the pull request template in `.github/pull_request_template.md`
+- Link to the corresponding issue when one exists (e.g., `Fixes #123`)
+- Keep descriptions concise
+- Include a bulleted list of changes at the conceptual level with reasons for
+  each change so reviewers can scan quickly

.kiro/steering/structure.md

@@ -72,6 +72,47 @@ inclusion: always
 - **External Data**: Graph data is queried directly from the connected graph
   databases and is not owned or persisted by Graph Explorer
 
+## Schema Storage
+
+Schema discovery is expensive in both time and database compute, so the
+discovered schema is persisted in IndexedDB (via localforage) as a
+`SchemaStorageModel`. This acts as a persistent cache per connection.
+
+Key files:
+
+- `src/core/StateProvider/schema.ts` — `SchemaStorageModel` type, Jotai atoms,
+  and incremental update logic
+- `src/core/ConfigurationProvider/types.ts` — `EdgeConnection`,
+  `VertexTypeConfig`, `EdgeTypeConfig`, and related types
+- `src/hooks/useSchemaSync.ts` — schema sync orchestration
+- `src/connector/queries/edgeConnectionsQuery.ts` — edge connection discovery
+
+### Edge Connections
+
+Edge connections (`EdgeConnection[]`) describe relationships between vertex
+types and are used by the Schema Explorer feature. Because the edge connection
+query can be expensive and unreliable, it runs separately from the main schema
+sync so that a failure only affects Schema Explorer — all other features work
+without edge connections.
+
+The `edgeConnections` property on `SchemaStorageModel` has three meaningful
+states:
+
+- `undefined` — edge connections have not been successfully discovered (query
+  not run or errored)
+- `[]` (empty array) — query succeeded but no edge connections exist
+- populated array — query succeeded with results
+
+If the edge connection query fails, the error is stored in the schema via the
+`edgeConnectionDiscoveryFailed` flag.
+
+### Incremental Schema Growth
+
+As users explore the graph, queries may return vertex/edge types or attributes
+not present in the initial schema sync. These are automatically merged into the
+stored schema via `updateSchemaFromEntities()`, causing the schema to grow more
+complete over time.
+
 ## Branded Types
 
 The project uses branded types from `@/utils` for type safety. These prevent

AGENTS.md

@@ -164,3 +164,12 @@ src/
 ### Testing
 
 See `.kiro/steering/testing.md` for testing patterns and examples.
+
+### Project Management
+
+See `.kiro/steering/project-management.md` for project management guidelines.
+
+### Project Organization
+
+See `.kiro/steering/structure.md` for code organization patterns and
+conventions.