refactor: move API schemas to api-schema/ and validation outputs to test/ (#115)

* refactor: move API schemas to api-schema/ and validation outputs to test/

- Move OpenAPI, AsyncAPI, and Arazzo specs from docs/reference/apis to api-schema/
- Move validation reports/databases to test/outputs/api-validation/
- Update all path references in Makefile, scripts, and documentation
- Update GitHub URLs in version.go and OpenAPI spec

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* chore: remove obsolete documentation and legacy migrations

- Remove inline-schema-analysis.md (outdated)
- Remove microsoft-entra-id-saml-claims.json (unused reference)
- Remove legacy migration files (superseded by current migrations)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: ericfitz

.github/workflows/security.yml

@@ -84,9 +84,9 @@ jobs:
       - name: Validate OpenAPI specification
         run: |
           # JSON syntax check
-          jq empty docs/reference/apis/tmi-openapi.json
+          jq empty api-schema/tmi-openapi.json
           # Vacuum linting with OWASP rules
-          vacuum lint -r vacuum-ruleset.yaml docs/reference/apis/tmi-openapi.json
+          vacuum lint -r vacuum-ruleset.yaml api-schema/tmi-openapi.json
 
   dependency-review:
     name: Dependency Review

.gitignore

@@ -48,6 +48,8 @@
 !.claude/**
 !.github/
 !.github/**
+!api-schema/
+!api-schema/**
 
 # heroku
 !.godir
@@ -82,10 +84,6 @@ scripts/configure-heroku-env.sh
 .dedupe/
 **/__pycache__/
 **/*.pyc
-docs/reference/apis/openapi-validation-report.json
-docs/reference/apis/openapi-validation.db
-docs/reference/apis/asyncapi-validation-report.json
-
 # OpenAPI backup files
 *.json.backup
 

.version

@@ -1,5 +1,5 @@
 {
   "major": 0,
   "minor": 272,
-  "patch": 4
+  "patch": 6
 }

CLAUDE.md

@@ -8,7 +8,7 @@ This repository contains API documentation and Go implementation for a Collabora
 
 ## Key Files
 
-- docs/reference/apis/tmi-openapi.json - OpenAPI specification
+- api-schema/tmi-openapi.json - OpenAPI specification
 - api/store.go - Generic typed map storage implementation
 - api/server.go - Main API server with WebSocket support
 - api/websocket.go - WebSocket hub for real-time collaboration
@@ -139,7 +139,7 @@ TMI uses [Chainguard](https://chainguard.dev/) container images for enhanced sec
 - Use jq to selectively query or modify the openapi schema
 - Validate OpenAPI: `make validate-openapi` (validates JSON syntax with jq, then runs Vacuum linting with OWASP rules)
   - Requires only `jq` and `vacuum` binaries (no Python or Node.js dependencies)
-  - Outputs structured JSON report to `docs/reference/apis/openapi-validation-report.json`
+  - Outputs structured JSON report to `api-schema/openapi-validation-report.json`
   - Configuration: `vacuum-ruleset.yaml` (extends `vacuum:oas` recommended + `vacuum:owasp` all)
 - **Public Endpoints**: TMI has 17 public endpoints (OAuth, OIDC, SAML) marked with vendor extensions (`x-public-endpoint`, `x-authentication-required`, `x-public-endpoint-purpose`)
   - These endpoints are intentionally accessible without authentication per RFCs (8414, 7517, 6749, SAML 2.0)
@@ -210,10 +210,10 @@ TMI uses the Arazzo specification (OpenAPI Initiative) to document API workflow
 
 **Files**:
 
-- `docs/reference/apis/tmi.arazzo.yaml` - Generated Arazzo specification (YAML)
-- `docs/reference/apis/tmi.arazzo.json` - Generated Arazzo specification (JSON)
-- `docs/reference/apis/api-workflows.json` - TMI workflow knowledge base (source)
-- `docs/reference/apis/arazzo-generation.md` - Complete documentation
+- `api-schema/tmi.arazzo.yaml` - Generated Arazzo specification (YAML)
+- `api-schema/tmi.arazzo.json` - Generated Arazzo specification (JSON)
+- `api-schema/api-workflows.json` - TMI workflow knowledge base (source)
+- `api-schema/arazzo-generation.md` - Complete documentation
 
 **Tools**:
 
@@ -592,7 +592,7 @@ Key developer documentation:
 ## User Preferences
 
 - After changing any file, run `make lint` and fix any issues caused by the change
-- After changing the OpenAPI specification (`docs/reference/apis/tmi-openapi.json`):
+- After changing the OpenAPI specification (`api-schema/tmi-openapi.json`):
   1. Run `make validate-openapi` and fix any validation issues
   2. Run `make generate-api` to regenerate the API code
   3. Run `make lint` and fix any linting issues
@@ -676,7 +676,7 @@ When asked to commit changes:
 
 ### OpenAPI Integration
 
-- API code generated from docs/reference/apis/tmi-openapi.json using oapi-codegen v2
+- API code generated from api-schema/tmi-openapi.json using oapi-codegen v2
 - Uses Gin web framework (not Echo) with oapi-codegen/gin-middleware for validation
 - OpenAPI validation middleware clears security schemes (auth handled by JWT middleware)
 - Generated types in api/api.go include Gin server handlers and embedded spec

Makefile

@@ -208,7 +208,7 @@ clean-build:
 
 generate-api:
 	$(call log_info,"Generating API code from OpenAPI specification...")
-	@oapi-codegen -config oapi-codegen-config.yml docs/reference/apis/tmi-openapi.json
+	@oapi-codegen -config oapi-codegen-config.yml api-schema/tmi-openapi.json
 	$(call log_success,"API code generated: api/api.go")
 
 
@@ -1352,13 +1352,13 @@ arazzo-scaffold: arazzo-install
 arazzo-enhance:
 	$(call log_info,Enhancing with TMI workflow data...)
 	@uv run scripts/enhance-arazzo-with-workflows.py
-	$(call log_success,Enhanced Arazzo created at docs/reference/apis/tmi.arazzo.{yaml,json})
+	$(call log_success,Enhanced Arazzo created at api-schema/tmi.arazzo.{yaml,json})
 
 validate-arazzo:
 	$(call log_info,Validating Arazzo specifications...)
 	@uv run scripts/validate-arazzo.py \
-		docs/reference/apis/tmi.arazzo.yaml \
-		docs/reference/apis/tmi.arazzo.json
+		api-schema/tmi.arazzo.yaml \
+		api-schema/tmi.arazzo.json
 	$(call log_success,Arazzo specifications are valid)
 
 generate-arazzo: arazzo-scaffold arazzo-enhance validate-arazzo
@@ -1371,11 +1371,11 @@ arazzo-all: arazzo-install generate-arazzo
 # OPENAPI/ASYNCAPI VALIDATION
 # ============================================================================
 
-OPENAPI_SPEC := docs/reference/apis/tmi-openapi.json
-OPENAPI_VALIDATION_REPORT := docs/reference/apis/openapi-validation-report.json
-OPENAPI_VALIDATION_DB := docs/reference/apis/openapi-validation.db
-ASYNCAPI_SPEC := docs/reference/apis/tmi-asyncapi.yml
-ASYNCAPI_VALIDATION_REPORT := docs/reference/apis/asyncapi-validation-report.json
+OPENAPI_SPEC := api-schema/tmi-openapi.json
+OPENAPI_VALIDATION_REPORT := test/outputs/api-validation/openapi-validation-report.json
+OPENAPI_VALIDATION_DB := test/outputs/api-validation/openapi-validation.db
+ASYNCAPI_SPEC := api-schema/tmi-asyncapi.yml
+ASYNCAPI_VALIDATION_REPORT := test/outputs/api-validation/asyncapi-validation-report.json
 
 validate-openapi:
 	$(call log_info,Validating OpenAPI specification...)

README.md

@@ -43,7 +43,7 @@ The complete development environment (server + database + Redis) will start auto
 - `api/` - API types and handlers
 - `cmd/server/` - Server entry point and configuration
 - `tmi-api-v1_0.md` - API documentation
-- `docs/reference/apis/tmi-openapi.json` - OpenAPI specification
+- `api-schema/tmi-openapi.json` - OpenAPI specification
 
 ## Architecture
 

docs/reference/apis/api-workflows.json api-schema/api-workflows.jsondocs/reference/apis/api-workflows.json renamed to api-schema/api-workflows.json

@@ -189,7 +189,7 @@
           },
           "api": {
             "version": "1.0.0",
-            "specification": "https://github.com/ericfitz/tmi/blob/main/docs/reference/apis/tmi-openapi.json"
+            "specification": "https://github.com/ericfitz/tmi/blob/main/api-schema/tmi-openapi.json"
           },
           "operator": {
             "name": "Example Organization",