Update Documentation and Cross-References
Objective
Complete documentation updates across README, GitLab Wiki, and cross-project references to reflect the new structure.
Root README Update
New README Structure
```markdown
🎨 Technical Guide - Standards Library
The authoritative source for design tokens, API standards, and validators for the LLM Platform ecosystem.
📦 What's Included
- Design Tokens: Colors, typography, spacing, motion, icons
- API Registry: Central discovery index for all platform APIs
- Validators: Brand compliance and API standards enforcement
- Shared Schemas: Common OpenAPI components
🚀 Quick Start
Installation
```bash npm install @bluefly/technical-guide ```
Usage
```typescript // Import design tokens import { colors, typography, spacing } from '@bluefly/technical-guide/tokens';
// Use in your app const primaryColor = colors.primary[600]; const headingFont = typography.families.display;
// Validate brand compliance import { validateBrand } from '@bluefly/technical-guide/validation'; const result = validateBrand(myDesign); ```
CLI Commands
```bash
Validate brand compliance
technical-guide validate-brand
Validate OpenAPI spec
technical-guide validate-api
Check project standards
technical-guide check-standards
Export tokens in different formats
technical-guide export-tokens --format css ```
📚 Documentation
- Wiki: Complete Documentation
- API Docs: Design Token API
- Migration Guide: Reorganization Guide
🔄 What Changed (Oct 2025)
This repository was reorganized from a mixed-purpose repo into a focused standards library:
Services Migrated
OpenAPI Specs Decentralized
- Each microservice now owns its API spec
- See: #4
- Central registry: `openapi/registry.yaml`
Documentation Moved to Wiki
- Brand guidelines → GitLab Wiki
- API documentation → GitLab Wiki
- See: #6
Rationale
See Epic: #1 - Technical Guide Reorganization
��️ Architecture Principles
- API-First: OpenAPI 3.1 specifications drive development
- DRY: Single source of truth for all standards
- Type-Safe: Zod validation + TypeScript
- No Shell Scripts: Production-grade tooling only
- GitLab-Driven: Issues for tasks, Wiki for docs
🤝 Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests: `npm test`
- Submit merge request
📄 License
MIT License - see LICENSE
🔗 Related Projects
- OSSA - Open Standards for Scalable Agents
- agent-router - API Gateway
- studio-ui - UI Component Library
- agent-buildkit - Build Tools
Built with Production Architecture principles. No shortcuts. No hacks. Production-ready. ```
GitLab Wiki Pages to Create
Home Page
-
Overview of technical-guide -
What's included -
Quick navigation -
Links to key pages
Brand Guidelines Section
-
Brand Guidelines Overview -
Color System (from colors.md) -
Typography (from typography.md) -
Logo Usage -
Accessibility Standards -
Design Foundations -
Icons -
Layout -
Motion
-
OpenAPI Registry Section
-
OpenAPI Registry Overview -
How to Register an API -
Registry Structure -
Discovery Process -
Contributing Specs
Integrations Section
-
Apidog Integration (now in agent-router) -
Design System API (now in studio-ui) -
How services were migrated
Migration Guide
-
Why we reorganized -
What moved where -
How to update your project -
Breaking changes -
Timeline
Cross-Project Documentation Updates
agent-router README
-
Add section on apidog integration -
Document new endpoints -
Link to technical-guide
studio-ui README
-
Add section on design-system API -
Document token usage -
Link to technical-guide
agent-buildkit README
-
Add apidog commands documentation -
Document validator integration -
Link to technical-guide
All common_npm Projects
-
Update README to mention technical-guide -
Document token usage -
Add installation instructions
Update OpenAPI Specs
Add x-documentation Links
```yaml
In each OpenAPI spec
info: x-documentation: wiki: https://gitlab.bluefly.io/llm/technical-guide/-/wikis/home package: https://www.npmjs.com/package/@bluefly/technical-guide issues: https://gitlab.bluefly.io/llm/technical-guide/-/issues ```
Automated Wiki Sync
Setup Wiki Sync Script
```typescript // scripts/sync-wiki.ts import { GitLabWikiService } from '@bluefly/agent-protocol';
async function syncWiki() { const wiki = new GitLabWikiService();
// Auto-generate token documentation await wiki.createPage({ slug: 'design-tokens', title: 'Design Tokens', content: generateTokenDocs() });
// Auto-generate API registry docs await wiki.createPage({ slug: 'api-registry', title: 'API Registry', content: generateRegistryDocs() }); } ```
Add to CI/CD
```yaml
.gitlab-ci.yml
sync:wiki: stage: deploy script: - npm run sync:wiki only: - main when: on_success ```
Link All Related Issues
Update Epic #1
-
Link all child issues (#2-#17) -
Update status -
Mark completed tasks
Cross-Link Issues
-
Each issue links to Epic #1 -
Dependencies linked -
Related issues linked
Verification
Check All Links
-
README links work -
Wiki links work -
Cross-project links work -
Issue links work -
No broken references
Documentation Complete
-
All services documented -
All migrations documented -
Usage examples provided -
API docs generated -
CLI help accurate
Tasks
-
Write new README -
Create Wiki home page -
Migrate brand guidelines to Wiki -
Create OpenAPI registry docs -
Write migration guide -
Update agent-router README -
Update studio-ui README -
Update agent-buildkit README -
Update all common_npm READMEs -
Add x-documentation to specs -
Create wiki sync script -
Add wiki sync to CI -
Link all related issues -
Verify all links work
Related
Success Criteria
-
✅ README complete and accurate -
✅ Wiki fully populated -
✅ All cross-references work -
✅ Migration guide helpful -
✅ No broken links -
✅ All projects reference technical-guide correctly -
✅ Documentation discoverable -
✅ Epic #1 can be closed