Docs/pypi technical readme

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,6 +1,6 @@
 ---
 name: Bug report
-about: Something in Open AURA is broken
+about: Something in OpenAURA is broken
 labels: [bug]
 ---
 

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,6 +1,6 @@
 ---
 name: Feature request
-about: Suggest an addition or change to Open AURA
+about: Suggest an addition or change to OpenAURA
 labels: [enhancement]
 ---
 
@@ -14,9 +14,9 @@ labels: [enhancement]
 
 ## Alternatives considered
 
-## Does it fit Open AURA's scope?
+## Does it fit OpenAURA's scope?
 
-Open AURA is **stateless, CI-native, agent-generated weekly briefs**. It is not a
+OpenAURA is **stateless, CI-native, agent-generated weekly briefs**. It is not a
 dashboard, not a server, not a SaaS. Features that require persistent state, a UI,
 or a hosted service are unlikely to land.
 

.github/scorecard.yml

@@ -6,7 +6,7 @@ annotations:
   - checks:
       - pinned-dependencies
     reasons:
-      - reason: not-applicable # Open AURA is a Python library; CI intentionally resolves package metadata across supported Python versions.
+      - reason: not-applicable # OpenAURA is a Python library; CI intentionally resolves package metadata across supported Python versions.
   - checks:
       - fuzzing
     reasons:

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Contributing to Open AURA
+# Contributing to OpenAURA
 
-Thanks for your interest in contributing! Open AURA is small and opinionated — the rules
+Thanks for your interest in contributing! OpenAURA is small and opinionated — the rules
 below keep it that way.
 
 ## Ground rules

PYPI.md

@@ -0,0 +1,142 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pradelgorithm/openaura/main/brandbook/openaura-logo.svg" alt="OpenAURA logo" width="420">
+</p>
+
+[![PyPI](https://img.shields.io/pypi/v/open-aura?logo=pypi&logoColor=white)](https://pypi.org/project/open-aura/)
+[![Python](https://img.shields.io/pypi/pyversions/open-aura?logo=python&logoColor=white)](https://pypi.org/project/open-aura/)
+[![CI](https://github.com/pradelgorithm/openaura/actions/workflows/ci.yml/badge.svg)](https://github.com/pradelgorithm/openaura/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/pradelgorithm/openaura/actions/workflows/codeql.yml/badge.svg)](https://github.com/pradelgorithm/openaura/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/pradelgorithm/openaura/badge)](https://securityscorecards.dev/viewer/?uri=github.com/pradelgorithm/openaura)
+[![Coverage](https://codecov.io/gh/pradelgorithm/openaura/graph/badge.svg)](https://codecov.io/gh/pradelgorithm/openaura)
+[![License](https://img.shields.io/badge/License-Apache_2.0-3b82f6.svg)](https://github.com/pradelgorithm/openaura/blob/main/LICENSE)
+
+OpenAURA is a CI-native Python CLI that generates recurring project briefs from
+delivery signals and writes markdown reports into `aura-docs/`.
+
+This page is the technical package reference. The human/product README lives in the
+[GitHub repository](https://github.com/pradelgorithm/openaura#readme).
+
+## Requirements
+
+- Python 3.11 or newer
+- A model provider key for Anthropic or OpenAI
+- At least one signal connector, currently GitHub or Azure DevOps
+
+The project CI verifies Python 3.11, 3.12, 3.13, and 3.14.
+
+## Installation
+
+```bash
+python -m pip install open-aura
+```
+
+The package installs the `aura` console command.
+
+## Configuration
+
+Create `aura.config.yml` at the root of the repository where briefs should be written:
+
+```yaml
+project: "my-project"
+trigger: weekly
+schedule: "friday-5pm"
+model: "anthropic:claude-sonnet-4-6"
+
+signals:
+  github:
+    repo: "owner/repository"
+    token_env: GITHUB_TOKEN
+    default_branch: main
+
+kpis:
+  - throughput
+  - cycle_time
+  - blockers
+  - bug_count
+
+custom_kpis: []
+
+output:
+  folder: "aura-docs"
+```
+
+Supported `trigger` values are:
+
+- `weekly`
+- `on-merge`
+- `both`
+
+The `schedule` field is documentation for humans. The actual cron schedule belongs
+in your CI workflow.
+
+## Environment Variables
+
+OpenAURA reads secret values from environment variables. The config file stores only
+the variable names.
+
+| Purpose | Default variable |
+|---|---|
+| Anthropic models | `ANTHROPIC_API_KEY` |
+| OpenAI models | `OPENAI_API_KEY` |
+| GitHub connector | `GITHUB_TOKEN` |
+| Azure DevOps org | `AZURE_DEVOPS_ORG` |
+| Azure DevOps project | `AZURE_DEVOPS_PROJECT` |
+| Azure DevOps token | `AZURE_DEVOPS_TOKEN` |
+
+Model strings beginning with `anthropic:` require `ANTHROPIC_API_KEY`. Model strings
+beginning with `openai:` require `OPENAI_API_KEY`.
+
+## CLI
+
+```bash
+aura validate
+aura run
+aura run --dry-run
+aura run --trigger on-merge
+aura manifesto
+```
+
+`aura validate` checks the config and required environment variables without making
+API or LLM calls.
+
+`aura run` gathers signals, scores the project state, summarizes the brief, and writes
+markdown to the configured output folder.
+
+`aura run --dry-run` prints the structured brief JSON instead of writing a file.
+
+## GitHub Actions
+
+Install OpenAURA in a workflow with pip:
+
+```yaml
+- uses: actions/setup-python@v6
+  with:
+    python-version: "3.13"
+
+- run: python -m pip install open-aura
+- run: aura validate
+- run: aura run
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+```
+
+The repository includes starter workflow templates for weekly, on-merge, and combined
+trigger modes.
+
+## Output
+
+By default, briefs are written to:
+
+```text
+aura-docs/
+```
+
+Each brief is markdown, intended to be committed back to the same repository by CI.
+
+## Links
+
+- Source: https://github.com/pradelgorithm/openaura
+- Issues: https://github.com/pradelgorithm/openaura/issues
+- Security policy: https://github.com/pradelgorithm/openaura/blob/main/SECURITY.md

README.md

@@ -1,7 +1,9 @@
 <!-- markdownlint-disable MD033 MD041 -->
 <div align="center">
 
-<h1>AURA</h1>
+<p>
+  <img src="brandbook/openaura-logo.svg" alt="OpenAURA logo" width="420">
+</p>
 
 <p><strong>Agentic Updates, Reviews, and Accountability.</strong></p>
 
@@ -209,7 +211,7 @@ outruns manual reporting.
 
 ### 1. Install
 
-Open AURA supports Python 3.11 and newer. The CI matrix currently verifies Python
+OpenAURA supports Python 3.11 and newer. The CI matrix currently verifies Python
 3.11, 3.12, 3.13, and 3.14.
 
 ```bash

SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Supported versions
 
-Open AURA is pre-1.0. Only the latest minor release receives security patches.
+OpenAURA is pre-1.0. Only the latest minor release receives security patches.
 
 | Version | Supported |
 |---------|-----------|
@@ -55,7 +55,7 @@ once a fix ships, crediting the reporter unless anonymity is requested.
 
 ## Secrets handling expectations
 
-Open AURA runs in CI and reads signals from external APIs. It:
+OpenAURA runs in CI and reads signals from external APIs. It:
 
 - Accepts secrets only from environment variables (never from config files).
 - Never logs secret values; tokens are redacted in error messages.

openaura/__init__.py

@@ -1,4 +1,4 @@
-"""Open AURA — Agentic Updates, Reviews, and Accountability."""
+"""OpenAURA — Agentic Updates, Reviews, and Accountability."""
 
 from __future__ import annotations
 

openaura/agents/_core.py

@@ -43,7 +43,7 @@ def model_id(config_model: str) -> str:
     """Build the Pydantic AI model string.
 
     Provider-prefixed strings pass through unchanged. Bare model names remain
-    Anthropic for backwards compatibility with early Open AURA configs.
+    Anthropic for backwards compatibility with early OpenAURA configs.
     """
     if ":" in config_model:
         return config_model
@@ -58,6 +58,6 @@ def model_ref(config_model: str | Model) -> str | Model:
 
 
 def model_api_key_env_var(config_model: str) -> str | None:
-    """Return the API key env var Open AURA can infer from a Pydantic AI model string."""
+    """Return the API key env var OpenAURA can infer from a Pydantic AI model string."""
     provider = model_id(config_model).split(":", maxsplit=1)[0]
     return MODEL_PROVIDER_ENV_VARS.get(provider)

openaura/instructions/manifesto.md

@@ -1,6 +1,6 @@
 # AURA Manifesto
 
-Open AURA is not a framework in the heavy sense. It is an update protocol: a small,
+OpenAURA is not a framework in the heavy sense. It is an update protocol: a small,
 repeatable way for any repo to turn delivery signals into accurate project briefs.
 
 The protocol exists so teams can stop translating work into status by hand. A repo

openaura/main.py

@@ -18,7 +18,7 @@
 from openaura.models.config import AuraConfig, Trigger
 from openaura.output import markdown as md_out
 
-app = typer.Typer(add_completion=False, no_args_is_help=True, help="Open AURA — weekly briefs.")
+app = typer.Typer(add_completion=False, no_args_is_help=True, help="OpenAURA — weekly briefs.")
 log = logging.getLogger("openaura")
 
 EXIT_CONFIG = 1

pyproject.toml

@@ -6,11 +6,11 @@ build-backend = "hatchling.build"
 name = "open-aura"
 version = "0.1.1"
 description = "Agentic Updates, Reviews, and Accountability — CI-native weekly project briefs powered by Pydantic AI."
-readme = "README.md"
+readme = "PYPI.md"
 requires-python = ">=3.11"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
-authors = [{ name = "Open AURA contributors" }]
+authors = [{ name = "OpenAURA contributors" }]
 keywords = ["ai", "agents", "devops", "pydantic-ai", "ci", "reporting", "openai", "anthropic"]
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -67,6 +67,7 @@ include = [
     "openaura",
     "tests",
     "README.md",
+    "PYPI.md",
     "MANIFESTO.md",
     "AGENTS.md",
     "LICENSE",