Merge pull request #1 from NeuroverseOS/claude/review-readme-governance-KIkOw

Claude/review readme governance k ik ow

Author: RegardsKiki2

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - run: npm ci
+      - run: npx tsc --noEmit
+      - run: npx vitest run
+      - run: docker build .

.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+*.tsbuildinfo

CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in the StarTalk community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project team at **team@neuroverseos.com**. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to StarTalk
+
+Thank you for your interest in contributing to StarTalk! This document provides guidelines and information for contributors.
+
+## How to Contribute
+
+### Reporting Issues
+
+- Use [GitHub Issues](https://github.com/NeuroverseOS/startalk/issues) to report bugs or suggest features.
+- Include steps to reproduce any bug, along with your environment details (Node version, OS, AI provider).
+- Check existing issues before opening a new one to avoid duplicates.
+
+### Submitting Changes
+
+1. Fork the repository.
+2. Create a feature branch from `main` (`git checkout -b feature/your-feature`).
+3. Make your changes and test them locally with `npm run dev`.
+4. Commit with clear, descriptive messages.
+5. Push to your fork and open a pull request against `main`.
+
+### Pull Request Guidelines
+
+- Keep PRs focused on a single change.
+- Describe what the PR does and why.
+- Reference any related issues.
+- Ensure your code follows the existing TypeScript style in the project.
+
+## Development Setup
+
+```bash
+git clone https://github.com/NeuroverseOS/startalk.git
+cd startalk
+npm install
+npm run dev
+```
+
+**Requirements:**
+- Node.js 20+
+- A MentraOS app API key (`MENTRA_APP_API_KEY` environment variable)
+- An AI provider API key (Anthropic or OpenAI, configured in app settings)
+
+## Areas of Contribution
+
+- **Zodiac sign definitions** (`src/signs/*.nv-world.md`): Refine traits, communication styles, compatibility, and mode directives.
+- **Interaction modes**: Improve mode selection logic and response quality.
+- **Governance integration**: Enhance trust scoring and guard evaluation.
+- **People memory**: Improve the persistent people chart system.
+- **Documentation**: Improve the README, guides, and inline comments.
+
+## Zodiac World File Format
+
+If you are contributing to sign definitions, each `.nv-world.md` file follows a structured format with frontmatter metadata and markdown sections for thesis, traits, communication, modes, compatibility, and tone. See any existing sign file in `src/signs/` as a reference.
+
+## Code of Conduct
+
+All contributors are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md). Please be respectful and constructive.
+
+## License
+
+By contributing to StarTalk, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE).

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2025 NeuroverseOS
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -0,0 +1,160 @@
+# StarTalk
+
+Astrological translator for MentraOS smart glasses. Set your signs. Tap. Get cosmic perspective.
+
+StarTalk is an AI-powered app that translates real-time social moments through the lens of your astrological chart. Running on MentraOS smart glasses, it gives you cosmic insight into what's happening around you — who you're talking to, how your signs interact, and what the stars have to say about the moment.
+
+## How It Works
+
+1. **Set your chart** in app settings: pick your Sun Sign (core identity) and optionally your Rising Sign (how you come across).
+2. **Tap or say "star"** to get a cosmic read on the current moment.
+3. **Tap again within 30 seconds** to expand or follow up.
+4. **Long press** to dismiss.
+
+StarTalk auto-selects the best interaction mode for each moment:
+
+| Mode | When It Fires | Example |
+|---|---|---|
+| **Translate** | Understanding someone else's behavior | "That's classic Taurus — they're not ignoring you, they're processing." |
+| **Reflect** | Understanding your own behavior | "Your Cancer moon is holding onto that comment. Let it go." |
+| **Challenge** | Falling into shadow traits | "You're avoiding the conversation. That's your Libra dodge." |
+| **Teach** | Learning the dynamic at play | "Fire signs speak to act. Water signs speak to connect." |
+| **Direct** | Need a clear recommendation | "Say it now. Aries energy rewards directness." |
+
+## Features
+
+### World Stacking
+
+StarTalk's core innovation. Your Sun Sign defines *who you are*; your Rising Sign defines *how you present*. StarTalk combines both into a unified personality lens, weighting the sun as dominant and the rising as a modifier. A Cancer with Aries rising gets emotionally deep reads delivered with bold directness.
+
+### People Memory
+
+Tell StarTalk about the people in your life:
+- "Sophie is a Cancer with Aries rising"
+- "talking to Sophie" (recalls her chart automatically)
+- "talking to a Taurus" (anonymous sign-based translation)
+
+People are persisted across sessions via MentraOS SimpleStorage.
+
+### Ambient Context
+
+With explicit opt-in (and bystander acknowledgment), StarTalk can listen to nearby conversation and factor it into reads. The audio buffer is configurable (1, 2, or 5 minutes) and is held in memory only — never persisted or transmitted beyond the AI call.
+
+### AI Provider Choice
+
+StarTalk uses a bring-your-own-key model. Choose between:
+- **Anthropic Claude** (Claude Haiku 4.5)
+- **OpenAI GPT** (GPT-4o Mini)
+
+No data is retained. Your API key goes directly to your chosen provider.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 20+
+- A MentraOS app API key
+- An Anthropic or OpenAI API key
+
+### Install and Run
+
+```bash
+git clone https://github.com/NeuroverseOS/startalk.git
+cd startalk
+npm install
+npm run dev
+```
+
+Set the `MENTRA_APP_API_KEY` environment variable before starting.
+
+### Docker
+
+```bash
+docker build -t startalk .
+docker run -p 3001:3001 -e MENTRA_APP_API_KEY=<your-key> startalk
+```
+
+The container runs as a non-root user on port 3001 with a built-in health check at `/health`.
+
+## Project Structure
+
+```
+startalk/
+  src/
+    server.ts             Main MentraOS app server
+    sign-loader.ts        Zodiac world parser and prompt builder
+    signs/
+      aries.nv-world.md   Zodiac sign world definitions (x12)
+      taurus.nv-world.md
+      ...
+  app_config.json         MentraOS settings schema
+  mentra.app.json         App metadata and permissions
+  Dockerfile              Multi-stage container build
+```
+
+### Zodiac World Files
+
+Each sign is defined in a `.nv-world.md` file — the NeuroverseOS world definition format. These structured markdown files contain frontmatter metadata (element, modality, ruling planet, dates) followed by sections for thesis, traits, communication style, the five interaction modes, compatibility, and tone. The sign-loader parses these at startup and caches them for prompt building.
+
+## NeuroverseOS Governance Integration
+
+StarTalk integrates with the [NeuroverseOS governance framework](https://github.com/NeuroverseOS/neuroverseos-governance), which provides three layers of runtime safety:
+
+- **Guard Engine** (`evaluateGuard()`): Checks all AI inputs and outputs against platform content rules before anything is displayed on the glasses.
+- **World Simulation** (`simulateWorld()`): Evaluates trust scores based on session behavior (AI call volume, activation patterns). Trust gates adjust response length invisibly to the user — from full 50-word reads at high trust down to glance-only 15-word reads at low trust, with responses disabled entirely if trust drops to revoked levels.
+- **Governed Executor** (`MentraGovernedExecutor`): Hooks into the MentraOS app lifecycle with callbacks for blocking or pausing actions that violate rules.
+
+The app declares its AI usage transparently in `mentra.app.json`, including that AI is opt-in only, keys are user-provided, and data retention is none.
+
+## Repository Governance Files
+
+Open-source projects benefit from clear governance — a set of files that define how the project is licensed, how people can contribute, what behavior is expected, and how security issues should be handled. GitHub recognizes these files and surfaces them in the repository's community profile. Here is how StarTalk uses each one:
+
+### LICENSE
+
+The [LICENSE](LICENSE) file contains the full text of the **Apache License 2.0**. This is the legal foundation of the project. It grants users a perpetual, royalty-free right to use, modify, and distribute StarTalk (including for commercial purposes), while requiring attribution and notice of changes. It also includes an explicit patent grant, which provides additional legal protection for contributors and users. The Apache 2.0 license was chosen for its balance of openness and legal clarity.
+
+### CONTRIBUTING.md
+
+The [CONTRIBUTING.md](CONTRIBUTING.md) file is the guide for anyone who wants to help improve StarTalk. It covers how to report bugs, submit pull requests, set up a development environment, and which areas of the codebase welcome contributions (sign definitions, interaction modes, governance integration, people memory, and documentation). Having clear contribution guidelines lowers the barrier to entry and keeps the project's quality consistent.
+
+### CODE_OF_CONDUCT.md
+
+The [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) sets behavioral expectations for everyone participating in the StarTalk community — contributors, maintainers, and users interacting in project spaces. It is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), the most widely adopted code of conduct in open source. It defines what positive participation looks like, what is not acceptable, and how violations are handled.
+
+### SECURITY.md
+
+The [SECURITY.md](SECURITY.md) file tells security researchers how to responsibly disclose vulnerabilities. Instead of opening public issues (which would expose the vulnerability to everyone), reporters email the team directly. The file also documents StarTalk's security architecture: BYO-key model with no key storage, opt-in ambient listening with bystander acknowledgment, governance-layer content filtering, and non-root Docker deployment.
+
+### Why Governance Files Matter
+
+These four files together form the governance foundation of an open-source project:
+
+- **LICENSE** answers: "Can I use this, and under what terms?"
+- **CONTRIBUTING.md** answers: "How do I help?"
+- **CODE_OF_CONDUCT.md** answers: "What behavior is expected?"
+- **SECURITY.md** answers: "What do I do if I find a vulnerability?"
+
+Without them, potential contributors don't know if they're welcome, users don't know their legal rights, and security researchers don't know how to reach you. GitHub tracks these files as part of your repository's "Community Standards" and will prompt you to add any that are missing.
+
+## Tech Stack
+
+- **Runtime**: Node.js 20+ / TypeScript
+- **Framework**: MentraOS SDK (`@mentra/sdk`)
+- **AI**: Anthropic Claude SDK, OpenAI SDK (user-selected)
+- **Governance**: NeuroverseOS governance framework
+- **Deployment**: Docker (multi-stage, non-root)
+
+## License
+
+StarTalk is licensed under the [Apache License 2.0](LICENSE).
+
+```
+Copyright 2025 NeuroverseOS
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+```

SECURITY.md

@@ -0,0 +1,46 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.0.x   | Yes                |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in StarTalk, please report it responsibly.
+
+**Do not open a public GitHub issue for security vulnerabilities.**
+
+Instead, email **team@neuroverseos.com** with:
+
+- A description of the vulnerability
+- Steps to reproduce it
+- The potential impact
+- Any suggested fixes (if applicable)
+
+We will acknowledge receipt within 48 hours and aim to provide an initial assessment within 5 business days.
+
+## Security Considerations
+
+### AI Provider API Keys
+
+- StarTalk uses a BYO-key model. User API keys are passed directly to the configured AI provider (Anthropic or OpenAI) and are never stored, logged, or transmitted elsewhere.
+- Keys are configured via the MentraOS app settings interface using the `secret` field type.
+
+### Ambient Listening
+
+- Ambient audio capture is opt-in only and disabled by default.
+- Users must explicitly enable ambient mode **and** acknowledge the bystander notice before any audio processing occurs.
+- Audio buffers are held in memory only and are not persisted to disk or transmitted beyond the AI provider call.
+
+### Governance and Content Safety
+
+- All AI inputs and outputs are checked through the NeuroverseOS governance framework (`evaluateGuard()`) before being displayed.
+- Trust scoring (`simulateWorld()`) provides behavioral degradation if anomalous usage patterns are detected.
+- The app declares `"data_retention": "none"` in its MentraOS manifest.
+
+### Docker Deployment
+
+- The container runs as a non-root user (`startalk`, uid 1001).
+- The Dockerfile uses a multi-stage build to minimize the attack surface of the runtime image.