feat: Add Docusaurus documentation site with visual architecture maps - #124
Open
zaebee wants to merge 24 commits into
Open
feat: Add Docusaurus documentation site with visual architecture maps#124zaebee wants to merge 24 commits into
zaebee wants to merge 24 commits into
Conversation
Co-authored-by: Ona <no-reply@ona.com>
- Add buf.build/community/neofelis-pydantic plugin to buf.gen.yaml - Output Pydantic models to packages/aura-core/src/aura_core/gen/ - Update arch_brain.json with Binary Bloodstream epoch - Add sacred rules: manual schema.py files are heretical Incineration list for Jules: - core/src/hive/proteins/persistence/schema.py - core/src/hive/proteins/reasoning/schema.py - core/src/hive/proteins/telemetry/schema.py - core/src/hive/proteins/guard/schema.py - core/src/hive/proteins/transaction/schema.py - core/src/hive/proteins/pulse/schema.py Co-authored-by: Ona <no-reply@ona.com>
* Integrate Binary Bloodstream and Normalized Action Protocol - Implement binary Protobuf event serialization via NATS JetStream. - Centralize brain path discovery with absolute path logging in aura-core. - Map raw negotiation strings to strict dna.proto ActionType enum. - Update Generator to increment metrics for both ACCEPT and COUNTER actions. - Purge generated code and enforce untracked stub hygiene. - Synchronize Telegram Bot with the unified binary metabolism. Co-authored-by: zaebee <305761+zaebee@users.noreply.github.com> * Fix CI failure and address code review feedback - Update CI workflows (.github/workflows/bee-keeper.yaml and ci-cd.yaml) to run 'make generate' and include the new generation paths. - Refactor brain discovery logic into 'aura-core' shared utility with standardized logging. - Fix 'TelegramGenerator' action mapping and ensure binary Protobuf events are strictly typed. - Update 'Makefile' to include a shim for betterproto google imports. - Maintain 'Crystalline' stub hygiene by ensuring no generated files are tracked in version control. - Synchronize all components to use the new 'ActionType' enum and 'resolve_brain_path' utility. Co-authored-by: zaebee <305761+zaebee@users.noreply.github.com> * Centralize negotiation logic and robustify brain discovery - Centralize `map_action` logic in `aura-core` for consistent action normalization across the Hive. - Implement robust `resolve_brain_path` using `find_hive_root` to correctly handle relative paths. - Update `AuraTransformer` and `TelegramGenerator` to use the centralized mapping. - Standardize logging in `aura-core` manifest using `structlog`. - Fix typing and linting issues introduced by centralization. - Verified system integrity with the full test suite (all tests pass). - Switched to 'untracked' stub hygiene in accordance with the Crystalline Standard. Co-authored-by: zaebee <305761+zaebee@users.noreply.github.com> --------- Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com> Co-authored-by: zaebee <305761+zaebee@users.noreply.github.com>
Implemented comprehensive documentation site using Docusaurus 3: **Core Features:** - Static site generation with React islands (ready for interactive components) - Cyberpunk-themed Hive branding (dark mode, #00f2ff primary) - Mermaid diagram support for visual architecture maps - GitHub Pages deployment via GitHub Actions - Auto-generation of Protobuf API documentation **Documentation Structure:** - Architecture guides (ATCG-M metabolism, Binary Bloodstream, Protein Mesh) - Protocol implementations (A/T/C/G/M nucleotides + Skills) - Visual guides (migrated from docs/visual/) - API reference (Protobuf types) - Interactive component placeholders (future React islands) **Visual Maps Added:** - docs/visual/metabolism.md - Complete signal flow through ATCG-M - docs/visual/hive/geography.md - Hive architecture layout - docs/visual/index.md - Enhanced with cellular ATCG-M diagram **Technical Setup:** - Bun package manager (faster than npm/yarn) - TypeScript with path aliases to frontend components - Migration script for existing docs - Protobuf doc generation script - GitHub Actions workflow for auto-deployment **Build Output:** - Site builds successfully in ~5 seconds - 25+ documentation pages - Optimized static assets - SEO-ready with sitemap Deploy URL (after merge): https://zaebee.github.io/aura/ Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Architectural Heresies Detected:
Reflective Insights (The Inquisitor's Eye):
Keeper's Reasoning
cc: @jules |
Removed unused blog directory with example posts since we disabled the blog feature in Docusaurus config. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Contributor
Summary of ChangesHello @zaebee, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a new, comprehensive documentation site built with Docusaurus, designed to centralize and clarify the project's architecture and protocols. A major underlying change is the transition to a strictly typed binary Protobuf messaging system via NATS JetStream, significantly improving the robustness and efficiency of inter-service communication. These changes aim to provide clearer insights into the system's design and operational flow, while enhancing the reliability of its internal data exchange. Highlights
Changelog
Ignored Files
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
Architectural Heresies Detected:
Keeper's ReasoningLLM Connectivity failure. Primary: Unterminated string starting at: line 58 column 16 (char 3281). Fallback: litellm.AuthenticationError: AuthenticationError: OpenAIException - Incorrect API key provided: NlXKSgAR********************CGHO. You can find your API key at https://platform.openai.com/account/api-keys. cc: @jules |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This is a massive and impressive pull request that introduces a comprehensive Docusaurus documentation site and fundamentally refactors the eventing system to a typed, binary protocol over NATS JetStream. The new documentation, complete with architectural diagrams, is a huge asset. The move from JSON to Protobuf for events, managed by a new JetStreamProvider, significantly improves type safety, performance, and robustness. The Makefile has also been nicely refactored for better maintainability. My review focuses on improving the portability and robustness of some of the new scripts and fixing a couple of minor issues.
* chore: Added train step for ci-cd. * chore: added uv install before train. * chore: added extra env vars for train ci-cd. * Enforce Crystalline stub hygiene and integrate Binary Bloodstream - Purge all generated Protobuf stubs from Git tracking to ensure a pure source-only repository. - Robustify `.gitignore` with anchored patterns to preserve root source files while ignoring deep generated folders. - Centralize `map_action` and `resolve_brain_path` in `aura-core` for system-wide consistency. - Implement Binary Bloodstream via strictly typed Protobuf events over NATS JetStream. - Update CI/CD workflows and bee-keeper agent to support dynamic stub generation. - Fix '0.0 success rate' issue by normalizing action types and metric increments. - Synchronize Telegram Bot with Unified Metabolism through a binary NATS listener. Co-authored-by: zaebee <305761+zaebee@users.noreply.github.com> * chore: fixed formatter. --------- Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com> Co-authored-by: zaebee <305761+zaebee@users.noreply.github.com>
Retargeting this PR from `feat/nats` to `main` surfaced one conflict, in docs/visual/index.md, and it does not resolve by picking a side: on the Organs row both versions are wrong. main: components/proteins — does not exist anywhere here: core/src/hive/proteins/ — pre-rename path, untracked leftover truth: core/src/aura_hive/hive/proteins/ Taken from this branch: the Bloodstream row, which now says Binary Protobuf over JetStream and matches HIVE_STATE.md; and the Digital Soul section, whose docs/arch_brain.json does exist. Taken from main: Citizens as agents/ + synapses/, since adapters/ was renamed. The Organs path is neither side's — it is the one the tree actually has. Two more references in the same table were broken on main already and are of the same kind, so they are fixed here rather than left for someone to trip over: FOUNDATION.md is FOUNDATIONS.md, and core/src/hive/membrane.py is core/src/aura_hive/hive/membrane/main.py. Three others are left alone as out of scope — imp/imp-001/hive.yaml, docs/standards/STD-001.md and docs/standards/IMP-001.md point at a standards structure that does not exist in the repository at all, which is a question rather than a typo. Checked every path the file names: everything else resolves. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
github-actions
Bot
added
the
needs-human
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements a comprehensive documentation site using Docusaurus 3 with cyberpunk-themed Hive branding and visual architecture maps.
Key Features
📚 Documentation Structure
docs/visual/with enhanced Mermaid diagrams🎨 Design & Branding
🔧 Technical Implementation
protoc-gen-doc🗺️ Visual Maps Added
docs/visual/metabolism.md- Complete ATCG-M signal flowdocs/visual/hive/geography.md- Hive architecture layoutdocs/visual/index.md- Enhanced cellular ATCG-M diagramBuild Stats
Deployment
Once merged, the site will be available at: https://zaebee.github.io/aura/
Setup Required
After merge, enable GitHub Pages:
Testing Locally
```bash
cd docs-site
bun install
bun start
Visit: http://localhost:3000/aura/
```
Future Work
For the glory of the Hive. 🐝