Skip to content

Commit 57b0878

Browse files
ericfitzclaude
ericfitz
and
claude
authored
docs: verify and migrate documentation to wiki (#114)
* docs: migrate database-schema-complete.md to wiki (SUPERSEDED) Verification found document is OUTDATED - based on legacy SQL migrations while TMI now uses GORM AutoMigrate with api/models/models.go as source. Key issues found and documented: - Migration paths incorrect (now in docs/reference/legacy-migrations/) - Schema management approach changed to GORM AutoMigrate - Several fields/tables missing (cwe_id, cvss, alias, user_preferences) - Make target names incorrect (reset-db-heroku not heroku-reset-db) - threat_type is now array, not TEXT Migrated useful design patterns to wiki Database-Schema-Reference.md: - UUID generation via GORM BeforeCreate - Provider-based identity scoping - Dual foreign key pattern for authorization - Threat modeling framework options - Asset type enumeration Original file moved to docs/migrated/ with verification summary. Wiki page now serves as authoritative reference. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: verify and migrate documentation to wiki - Verified 66 markdown files against source code - Corrected numerous inaccuracies found during verification: - Updated outdated default values (quotas, rate limits) - Fixed wrong endpoints and provider IDs - Corrected migration system references (golang-migrate to GORM) - Fixed framework references (Echo to Gin) - Migrated all verified content to wiki repository - Moved original files to docs/migrated/ with verification summaries - Added NEEDS-REVIEW markers for items requiring manual review - Created verify-migrate-doc skill for future documentation verification Key corrections: - OAuth provider: idp=test -> idp=tmi - Default max_active_invocations: 1 -> 3 - Default max_requests_per_minute: 100 -> 1000 - Health endpoint: /version -> / (root) - Webhook endpoint: /webhooks -> /webhooks/subscriptions Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
1 parent df41a38 commit 57b0878

File tree

82 files changed

+4653
-4032
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

82 files changed

+4653
-4032
lines changed

‎.claude/skills/verify-migrate-doc/SKILL.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
---
2+
name: verify-migrate-doc
3+
description: Verify documentation accuracy against source code and migrate to wiki. Use when asked to verify docs, migrate docs to wiki, or ensure documentation is accurate.
4+
argument-hint: <path-to-doc-file>
5+
allowed-tools: Read, Glob, Grep, Bash, WebSearch, WebFetch, Edit, Write
6+
context: fork
7+
agent: general-purpose
8+
---
9+
10+
# Documentation Verification and Migration Skill
11+
12+
You are a documentation verification and migration agent. Your task is to verify the accuracy of a documentation file and migrate it to the wiki.
13+
14+
## Input
15+
16+
The path to a documentation file is provided as: `$ARGUMENTS`
17+
18+
If no path is provided, ask the user to specify the documentation file to process.
19+
20+
## Critical Constraints
21+
22+
**PARALLEL EXECUTION WARNING**: Multiple instances of this skill may run simultaneously on different files. You MUST:
23+
- **ONLY modify the single file you were assigned** (the file at `$ARGUMENTS`)
24+
- **NEVER modify any other documentation files in the repo**
25+
- You MAY read any file in the repo for context
26+
- You MAY create or modify wiki files in `/Users/efitz/Projects/tmi.wiki/`
27+
- You MAY move the processed file to the migrated folder when complete
28+
29+
## Phase 1: Read and Understand
30+
31+
1. Read the documentation file at the specified path
32+
2. You may read other documentation files to understand context, but remember: **do not modify them**
33+
3. Identify all claims, references, and instructions in the document that need verification
34+
35+
## Phase 2: Verification
36+
37+
**TRUST NOTHING IN THE DOCUMENT** - Verify every claim against authoritative sources.
38+
39+
### 2.1 Internal References (Code/Config in TMI Repo)
40+
41+
For each reference to something in the TMI codebase:
42+
43+
**File Path References**:
44+
- If the document mentions a file path (e.g., "see `api/server.go`"), verify the file exists at that exact path
45+
- Use Glob or Read to confirm existence
46+
- If incorrect: Correct the path in the document if you can find the right file, OR mark with `<!-- NEEDS-REVIEW: File not found: [path] -->`
47+
48+
**Setting/Configuration References**:
49+
- If the document mentions a setting name (e.g., "set `TMI_DATABASE_URL`"), verify in SOURCE CODE (not config files) that this setting is actually parsed and used
50+
- Search for the setting name in `.go` files to find where it's read
51+
- Verify acceptable values match what's documented
52+
- If incorrect: Update the document OR mark with `<!-- NEEDS-REVIEW: Setting [name] not found in source -->`
53+
54+
**Behavior Claims**:
55+
- If the document says "when X happens, the server does Y", find the code that implements this behavior
56+
- Use Grep to search for relevant functions/handlers
57+
- Read the source code to confirm the behavior
58+
- If incorrect: Update the document OR mark with `<!-- NEEDS-REVIEW: Behavior not verified: [description] -->`
59+
60+
**Command/Make Target References**:
61+
- If the document mentions a make target (e.g., "`make build-server`"), verify it exists in the Makefile
62+
- If incorrect: Update OR mark with `<!-- NEEDS-REVIEW: Make target not found: [target] -->`
63+
64+
### 2.2 External/Third-Party References
65+
66+
For ANY reference to third-party tools, packages, or external documentation:
67+
68+
**Package Names**:
69+
- If the document mentions an exact package name (e.g., "`@openapi/codegen`", "`gin-gonic/gin`"), you MUST find **at least 2 independent internet sources** confirming the exact name
70+
- Use WebSearch to verify
71+
- If you cannot find 2 sources agreeing: Mark with `<!-- NEEDS-REVIEW: Package name not verified: [name] -->`
72+
73+
**Installation Commands**:
74+
- If the document says "install with `npm install foo`", verify with 2+ internet sources that this is the correct installation method
75+
- Use WebSearch to check official docs and reputable sources
76+
77+
**External Tool Behavior**:
78+
- If the document claims an external tool behaves a certain way, verify with 2+ internet sources
79+
- Example: "golangci-lint uses .golangci.yml by default" - search to confirm
80+
81+
**URLs**:
82+
- If the document contains URLs, verify they are still valid using WebFetch
83+
- Mark broken links with `<!-- NEEDS-REVIEW: Broken link: [url] -->`
84+
85+
### 2.3 Verification Evidence
86+
87+
As you verify each claim, keep track of what you verified and how. You will include a summary at the end of the document.
88+
89+
## Phase 3: Update Document
90+
91+
After verification, update the original document:
92+
93+
1. Fix any incorrect information you were able to verify the correct value for
94+
2. Add `<!-- NEEDS-REVIEW: ... -->` markers for anything you could not verify or that appears incorrect
95+
3. Add a verification summary at the end of the document:
96+
97+
```markdown
98+
<!--
99+
VERIFICATION SUMMARY
100+
Verified on: [date]
101+
Agent: verify-migrate-doc
102+
103+
Verified items:
104+
- [item]: [verification source/method]
105+
106+
Items needing review:
107+
- [item]: [reason]
108+
-->
109+
```
110+
111+
## Phase 4: Migrate to Wiki
112+
113+
The wiki repository is located at: `/Users/efitz/Projects/tmi.wiki/`
114+
115+
### 4.1 Analyze Content Categories
116+
117+
Review the document content and determine which wiki page(s) it should be merged into. The wiki has these main pages (among others):
118+
119+
- `Home.md` - Landing page
120+
- `API-Overview.md`, `API-Integration.md`, `REST-API-Reference.md`, `WebSocket-API-Reference.md` - API documentation
121+
- `Getting-Started-with-Development.md` - Developer setup
122+
- `Testing.md` - Testing documentation
123+
- `Database-Setup.md`, `Database-Operations.md` - Database docs
124+
- `Deploying-TMI-Server.md`, `Deploying-TMI-Web-Application.md` - Deployment
125+
- `Configuration-Reference.md` - Configuration settings
126+
- `Security-Best-Practices.md`, `Security-Operations.md` - Security
127+
- `Architecture-and-Design.md` - Architecture
128+
- `Debugging-Guide.md`, `Common-Issues.md` - Troubleshooting
129+
- `Webhook-Integration.md`, `Addon-System.md` - Integrations
130+
131+
### 4.2 Content Distribution
132+
133+
A single documentation file may have content suitable for multiple wiki pages. For example:
134+
- Setup instructions -> `Getting-Started-with-Development.md`
135+
- Configuration options -> `Configuration-Reference.md`
136+
- API details -> appropriate API page
137+
- Troubleshooting -> `Common-Issues.md` or `Debugging-Guide.md`
138+
139+
### 4.3 Update Wiki Pages
140+
141+
For each target wiki page:
142+
143+
1. Read the existing wiki page
144+
2. Find the appropriate section for the new content
145+
3. Integrate the content, avoiding duplication
146+
4. Maintain consistent formatting with the existing wiki style
147+
5. Update the wiki's `_Sidebar.md` if adding new sections
148+
149+
### 4.4 Cross-Reference
150+
151+
Add a note in the wiki indicating where the content came from:
152+
```markdown
153+
<!-- Migrated from: [original-path] on [date] -->
154+
```
155+
156+
## Phase 5: Mark as Migrated
157+
158+
After successful migration:
159+
160+
1. Create the migrated folder if it doesn't exist:
161+
```
162+
docs/migrated/
163+
```
164+
165+
2. Move the original file to the migrated folder, preserving the subdirectory structure:
166+
- Original: `docs/developer/setup/foo.md`
167+
- Migrated: `docs/migrated/developer/setup/foo.md`
168+
169+
3. The move operation should use `git mv` if possible to preserve history
170+
171+
## Output Summary
172+
173+
When complete, report:
174+
175+
1. **Verification Results**:
176+
- Number of items verified
177+
- Number of items needing review
178+
- List of any corrections made
179+
180+
2. **Migration Results**:
181+
- Which wiki pages were updated
182+
- What content was added to each
183+
184+
3. **File Status**:
185+
- Original location
186+
- New location (in migrated folder)
187+
188+
## Error Handling
189+
190+
If you encounter issues:
191+
- Cannot read the file: Report error and stop
192+
- File doesn't appear to be documentation: Report and ask for confirmation
193+
- Wiki repo not accessible: Complete verification but skip migration, report error
194+
- Uncertain about verification: Mark with NEEDS-REVIEW rather than guessing
195+
196+
## Example Verification
197+
198+
For a document containing:
199+
```markdown
200+
Install golangci-lint with `brew install golangci-lint`
201+
```
202+
203+
You would:
204+
1. WebSearch for "golangci-lint installation brew"
205+
2. Find at least 2 sources (official docs, GitHub repo, reputable guides) confirming `brew install golangci-lint`
206+
3. If confirmed: No change needed
207+
4. If not confirmed or different: Update or mark for review

‎.version‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
22
"major": 0,
33
"minor": 272,
4-
"patch": 2
4+
"patch": 4
55
}

‎CLAUDE.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -144,8 +144,7 @@ TMI uses [Chainguard](https://chainguard.dev/) container images for enhanced sec
144144
- **Public Endpoints**: TMI has 17 public endpoints (OAuth, OIDC, SAML) marked with vendor extensions (`x-public-endpoint`, `x-authentication-required`, `x-public-endpoint-purpose`)
145145
- These endpoints are intentionally accessible without authentication per RFCs (8414, 7517, 6749, SAML 2.0)
146146
- CATS fuzzing automatically skips `BypassAuthentication` tests on these paths to avoid false positives
147-
- See [docs/developer/testing/cats-public-endpoints.md](docs/developer/testing/cats-public-endpoints.md) for complete documentation
148-
- Update script: `./scripts/add-public-endpoint-markers.sh` (automatically adds vendor extensions)
147+
- See [docs/migrated/developer/testing/cats-public-endpoints.md](docs/migrated/developer/testing/cats-public-endpoints.md) for complete documentation
149148

150149
### CATS API Fuzzing
151150

@@ -180,15 +179,15 @@ CATS (Contract-driven Automatic Testing Suite) performs security fuzzing of the
180179
- TMI has 17 public endpoints (OAuth, OIDC, SAML) marked with `x-public-endpoint: true` vendor extension
181180
- CATS uses `--skipFuzzersForExtension=x-public-endpoint=true:BypassAuthentication` to avoid false positives
182181
- Public endpoints are intentionally accessible without authentication per RFCs (8414, 7517, 6749, SAML 2.0)
183-
- See [docs/developer/testing/cats-public-endpoints.md](docs/developer/testing/cats-public-endpoints.md) for complete documentation
182+
- See [docs/migrated/developer/testing/cats-public-endpoints.md](docs/migrated/developer/testing/cats-public-endpoints.md) for complete documentation
184183

185184
**Cacheable Endpoint Handling**:
186185

187186
- 6 discovery endpoints use `Cache-Control: public, max-age=3600` (intentionally cacheable per RFC 8414/7517/9728)
188187
- These endpoints are marked with `x-cacheable-endpoint: true` vendor extension
189188
- CATS uses `--skipFuzzersForExtension=x-cacheable-endpoint=true:CheckSecurityHeaders` to avoid false positives
190189
- CATS `CheckSecurityHeaders` fuzzer expects `no-store`, but caching discovery metadata is correct behavior
191-
- See [docs/developer/testing/cats-public-endpoints.md#cacheable-endpoints](docs/developer/testing/cats-public-endpoints.md#cacheable-endpoints) for details
190+
- See [docs/migrated/developer/testing/cats-public-endpoints.md#cacheable-endpoints](docs/migrated/developer/testing/cats-public-endpoints.md#cacheable-endpoints) for details
192191

193192
### Arazzo Workflow Generation
194193

‎api/version.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ var (
2929
// Minor version number
3030
VersionMinor = "272"
3131
// Patch version number
32-
VersionPatch = "2"
32+
VersionPatch = "4"
3333
// GitCommit is the git commit hash from build
3434
GitCommit = "development"
3535
// BuildDate is the build timestamp

‎docs/README.md‎

Lines changed: 0 additions & 75 deletions
This file was deleted.

0 commit comments

Comments
 (0)