Setting up project structure and initial files

README.md

@@ -4,7 +4,7 @@
 [![CI](https://github.com/Pmaster-dev/server/actions/workflows/ci.yml/badge.svg)](https://github.com/Pmaster-dev/server/actions/workflows/ci.yml)
 [![Pages](https://github.com/Pmaster-dev/server/actions/workflows/pages.yml/badge.svg)](https://github.com/Pmaster-dev/server/actions/workflows/pages.yml)
 
-Infrastructure and automation layer for the **Pmaster-dev / pinkycollie** ecosystem. Provides a serverless Python automation engine, shared OpenAPI contracts, and auth utilities consumed by downstream services.
+Infrastructure and automation layer for the **Pmaster-dev** core ecosystem. Provides a serverless Python automation engine, shared OpenAPI contracts, and auth utilities consumed by downstream services built on `magician-core`, `a2a`, and the AI SDK.
 
 📖 **Documentation →** [pmaster-dev.github.io/server](https://pmaster-dev.github.io/server)
 
@@ -52,7 +52,7 @@ OpenAPI contract: [`docs/openapi/automation.yaml`](docs/openapi/automation.yaml)
 
 ## Ecosystem
 
-See [`docs/pinkycollie-ecosystem-inventory.md`](docs/pinkycollie-ecosystem-inventory.md) for the full cross-org architecture map.
+See [`docs/ecosystem-inventory.md`](docs/ecosystem-inventory.md) for the full cross-org architecture map.
 
 ## License
 

docs/architecture/engines.md

@@ -0,0 +1,104 @@
+# MBTQ Kernel — Engine Capabilities
+
+The six engines below are the missing kernel capabilities identified in the
+MBTQ Business OS architecture.  Every product—dashboards, AI agents,
+mobile apps, sign-language models—sits **on top of** these foundations.
+
+See [`kernel.md`](kernel.md) for the data model they operate on.
+
+---
+
+## 1. Registry Engine
+
+**Responsibility:** Answer "what exists?" — maintain a live index of every
+kernel object (Person, Organization, Case, etc.) and expose it for lookup,
+search, and enumeration.
+
+**Input:** object type + optional filter criteria  
+**Output:** list of matching kernel object references (id, type, summary)
+
+**Existing coverage in `src/automation`:**  
+`ComponentRegistry` already implements a named-object registry pattern
+(register, deregister, lookup by name).  The kernel `RegistryEngine` extends
+this pattern to persistent, typed kernel objects.
+
+---
+
+## 2. Event Store Engine
+
+**Responsibility:** Answer "what happened?" — append-only log of every
+`Event` in the system.  Events are immutable facts.  Nothing is deleted;
+state is derived by replaying events.
+
+**Input:** `Event` record (type, actor, subject, timestamp, payload)  
+**Output:** event id; query interface returns ordered event streams
+
+**Existing coverage in `src/automation`:**  
+`AutomationEngine.trigger_type` already emits `TriggerEvent` objects that
+carry `event_type`, `event_id`, and `timestamp`.  The kernel `EventStoreEngine`
+generalises this into a durable, queryable log.
+
+---
+
+## 3. Workflow Engine
+
+**Responsibility:** Answer "what's next?" — resolve the current state of a
+`Workflow` instance, advance it on incoming events, and emit the next
+required action.
+
+**Input:** workflow template name + current state + triggering event  
+**Output:** next step(s) to execute; updated workflow state
+
+**Existing coverage in `src/automation`:**  
+`AutomationEngine` + `AutomationDefinition` already model trigger→steps
+pipelines.  The kernel `WorkflowEngine` adds state persistence, branching,
+and multi-step advancement on top of that foundation.
+
+---
+
+## 4. Decision Engine
+
+**Responsibility:** Answer "why?" — evaluate a decision policy (rule-based
+or AI-driven) against the current context and record a `Decision` with full
+rationale, actor, and timestamp.
+
+**Input:** decision type + context (Person, Case, Event, accessibility profile)  
+**Output:** `Decision` record (choice, confidence, rationale, policy version)
+
+**Existing coverage in `src/automation`:**  
+`Component.validate` already implements a binary decision contract
+`(bool, reason)`.  The kernel `DecisionEngine` generalises this into a
+multi-valued, auditable decision record stored in the `decisions` table.
+
+---
+
+## 5. Document Engine
+
+**Responsibility:** Answer "prove it" — manage the lifecycle of every
+`Document`: creation, versioning, format conversion, accessibility
+rendering, and archival.
+
+**Input:** document payload + metadata (type, owner, format, accessibility profile)  
+**Output:** `Document` record with storage reference, version, and rendered variants
+
+**Existing coverage in `src/automation`:**  
+`TextFileGuardrail` already enforces input validation rules on file payloads.
+The kernel `DocumentEngine` extends this to full document lifecycle management
+with accessibility-aware rendering.
+
+---
+
+## 6. Outcome Engine
+
+**Responsibility:** Answer "did it work?" — aggregate `Outcome` records
+attached to Cases, Projects, and Workflows; compute metrics; and surface
+progress against defined success criteria.
+
+**Input:** outcome type + subject reference (Case id, Project id, etc.) + measured value  
+**Output:** `Outcome` record; summary metrics; comparison against baseline
+
+**Existing coverage in `src/automation`:**  
+`RunResult` already captures `status`, `outputs`, `started_at`,
+`finished_at`, and `duration_ms` for each automation run—the same shape as
+an `Outcome`.  The kernel `OutcomeEngine` generalises this to domain-level
+outcome tracking.

docs/architecture/kernel.md

@@ -0,0 +1,91 @@
+# MBTQ Kernel — Data Model
+
+The MBTQ Business OS is not a collection of apps.  Every product—DeafAuth,
+PinkSync, VR4Deaf, FibonRose, MagicianCore—is a **view** into the same
+underlying system.  This document defines that system: its kernel objects,
+core database tables, and the accessibility-as-metadata pattern that
+influences every interaction.
+
+---
+
+## 11 Kernel Objects
+
+Everything that can happen in MBTQ is expressible as a combination of these
+objects:
+
+| Object | Description |
+|---|---|
+| **Person** | Any human actor: client, employee, contractor, partner |
+| **Organization** | Any institutional actor: employer, agency, vendor, partner org |
+| **Case** | A tracked interaction between a Person and an Organization (e.g. VR intake) |
+| **Project** | A time-boxed unit of work owned by a Person or Organization |
+| **Service** | A defined offering provided by an Organization |
+| **Accommodation** | An accessibility or reasonable-accommodation record attached to a Person |
+| **Document** | Any file, form, report, or artifact produced or consumed by the system |
+| **Workflow** | A reusable sequence of steps governing how work moves forward |
+| **Decision** | A recorded choice made by a person, agent, or policy rule |
+| **Outcome** | A measurable result tied to a Case, Project, or Workflow |
+| **Event** | An immutable fact that something happened (source of truth for the Event Store) |
+
+### Composite examples
+
+| Role | Kernel composition |
+|---|---|
+| VR Client | Person + Accommodation + Workflow + Outcome |
+| Entrepreneur | Person + Project + Document + Outcome |
+| Vendor | Organization + Service + Document |
+| State Agency | Organization + Workflow + Document + Outcome |
+| MagicianCore trigger | Event + Decision + Workflow |
+
+---
+
+## 8 Core Database Tables
+
+A minimal schema from which all products extend:
+
+```sql
+users           -- identity + accessibility profile
+organizations   -- institutional actors
+workflows       -- reusable step templates
+events          -- append-only fact log
+documents       -- files and structured forms
+accommodations  -- per-user accessibility records
+decisions       -- recorded choices with rationale
+outcomes        -- measured results
+```
+
+All domain tables (cases, projects, services, etc.) are **extensions** of
+these eight—either as join tables, typed sub-records, or views.
+
+---
+
+## Accessibility as Metadata
+
+Accessibility is not a feature module.  It is a **profile attached to every
+user** that influences every engine, workflow, document, and communication in
+the system.
+
+```json
+{
+  "user_id": "123",
+  "preferred_language": "ASL",
+  "communication_mode": "video",
+  "captions_required": true,
+  "screen_reader": false,
+  "preferred_format": "plain-text"
+}
+```
+
+Every engine reads this profile before acting.  A workflow that sends a
+notification checks `communication_mode`.  A document engine checks
+`preferred_format`.  A decision engine logs the language context with every
+`Decision` record.
+
+---
+
+## Relationship to `src/kernel`
+
+The Python package at `src/kernel/` implements the six engine capabilities
+described in [`engines.md`](engines.md).  The 8 core tables above define
+the shared persistence contract published in
+[`../openapi/kernel.yaml`](../openapi/kernel.yaml).

docs/ecosystem-inventory.md

@@ -0,0 +1,90 @@
+# Pmaster-dev ecosystem inventory
+
+## Objective
+
+Maintain `Pmaster-dev` infrastructure repos as the core foundation for an AI-agent-first ecosystem built on `magician-core`, `a2a` (Agent-to-Agent), and the AI SDK.
+
+## Ecosystem snapshot
+
+| Org | Key repos | Current role |
+|---|---|---|
+| `360magicians` | `magician-core`, `a2a`, `magician-sdk` | Core AI agent orchestration and Agent-to-Agent protocols |
+| `Pmaster-dev` | `server`, `docs`, `actions`, `electron`, `.github` | Infrastructure/automation layer, reusable tooling, shared contracts |
+
+## Kernel Layer — single source of truth for data
+
+All products are **views into the kernel**.  The kernel lives in `Pmaster-dev/server`.
+
+The kernel defines:
+
+- **11 kernel objects** — Person, Organization, Case, Project, Service, Accommodation, Document, Workflow, Decision, Outcome, Event (see [`docs/architecture/kernel.md`](architecture/kernel.md))
+- **8 core tables** — `users`, `organizations`, `workflows`, `events`, `documents`, `accommodations`, `decisions`, `outcomes`
+- **6 engine capabilities** — Registry, Event Store, Workflow, Decision, Document, Outcome (see [`docs/architecture/engines.md`](architecture/engines.md))
+- **Shared OpenAPI contracts** — [`docs/openapi/kernel.yaml`](openapi/kernel.yaml) imported by all downstream services
+- **Python implementation** — `src/kernel/` package, one module per engine
+
+No product creates its own parallel data model.  If a concept isn't in the kernel, it is proposed here first.
+
+---
+
+## Layer 1 — single source of truth for templates
+
+- Keep `Pmaster-dev/.github` as the org template hub:
+  - shared `CODEOWNERS`
+  - reusable workflows in `ci/` and `deployments/`
+  - shared pre-commit config
+- Mirror the same model in `360magicians` using `magician-core` as the workflow hub.
+- Replace duplicated per-repo workflows with reusable `workflow_call` workflows.
+
+## Layer 2 — standardized pipeline lifecycle
+
+Standard stage order for every repo:
+
+`[Scan/Lint] → [Build] → [Test] → [Security] → [Deploy/Publish]`
+
+Target mapping:
+
+- Scan: `pr-security.yml`, `semgrep.yml`, `codeql.yml`
+- Lint: `pylint.yml`, `super-linter.yml`
+- Build: `rust-ci.yml`, `nextjs.yml`, `deploy-marketing-site.yml`
+- Test: `vitest`, `pytest`
+- Deploy: `github-pages.yml`, `deploy.yml`, `release.yml`
+
+## Layer 3 — framework instances to align
+
+| Instance | Pmaster-dev | 360magicians |
+|---|---|---|
+| API server | `server/src/automation` | `magician-core` |
+| API docs | `docs/openapi/` | `a2a` protocol spec |
+| Desktop client | `electron` | — |
+| CI action | `actions/action.yml` | `magician-sdk` |
+| Marketing/docs site | — | `mbtq.dev` |
+| Web app | — | `magician-sdk` frontend |
+| Auth layer | — | `a2a` identity layer |
+
+## Layer 4 — integration method rule
+
+- Default to **REST** for user-initiated synchronous CRUD flows.
+- Use **Webhook** for asynchronous automation events (CI, release, cross-repo signals).
+- Defer **gRPC/tRPC** until latency/throughput needs justify protocol expansion.
+
+## Layer 5 — cross-org webhook bridge
+
+Reference flow:
+
+`Pmaster-dev/* push/release` → `Pmaster-dev/actions` → dispatch/webhook to `360magicians/magician-core` → update workflow state → run downstream checks → report status back to source PR/check.
+
+## Layer 6 — versioned artifacts
+
+- Machine-readable contracts: `docs/openapi/*.yaml`
+- Human-readable operational docs: `docs/api/`, `docs/guides/`
+- Agent/system context: `magician-core` agent definitions
+- Cross-org map (this file): `docs/ecosystem-inventory.md`
+
+## Priority sequence
+
+1. Commit this ecosystem inventory document in `Pmaster-dev/server`.
+2. Publish shared automation OpenAPI contracts under `docs/openapi/`.
+3. Refactor duplicated workflows into reusable `workflow_call` units.
+4. Wire webhook bridge from `Pmaster-dev/actions` to `360magicians/magician-core`.
+5. Standardize framework package versions across frontend repos.