docs: add AGENTS.md guidelines and initial task kanban

AGENTS.md

@@ -0,0 +1,19 @@
+# AGENTS.md — Auth-Yes System Guidelines & Operating Protocol
+
+## 1. Project Context
+Auth-Yes is a standalone, ultra-low-friction, zero-trust Identity and Access Management (IAM) fabric and WebAuthn Passkey authority.
+- **Runtime:** Deno 2.x (TypeScript 5.x)
+- **Architecture:** Modular Deno Workspace (`sdk/`, `server/`, `ui/`, `spire_ffi/`, `infra/`)
+- **Web API & SSR:** Hono with pure Hono SSR JSX (Strictly React-free)
+- **Workload Mesh:** ConnectRPC daemon + Rust SPIFFE/mTLS FFI crate (`spire_ffi/`)
+- **Data Layer:** Dedicated PostgreSQL 18 + Valkey 8 (L1/L2 RESP3 Client Tracking)
+- **Cookie Scope:** Wildcard `.atyg.org` domain scoping with host-collision sweep
+
+## 2. Key Architecture Standards
+1. **Zero-Dependency SDK:** `@auth-yes/sdk` must remain 100% free of backend/database imports. ConnectRPC contracts live in `sdk/gen/`.
+2. **Security:** Session invalidation and revocation MUST always be handled server-side (`deleteCookie` across host and wildcard domains).
+3. **Quality Gates:** Every PR must pass `deno fmt`, `deno task lint`, `deno task check`, and `deno test`.
+
+## 3. History & Context Link
+This repository was cleanly extracted from `ed-droid`.
+- **Reference Conversation:** `conversation://6a3fa402-ae0a-4231-9991-b0ff79a61e0f`

tasks/GUIDELINES.md

@@ -0,0 +1,86 @@
+# Task Management Guidelines
+
+This document outlines the standard operating procedure for the repository-based
+Kanban workflow using Markdown files to safely manage and track technical
+stories, architectural planning, and audits. All agents and developers must
+adhere to these guidelines.
+
+## A. The Filename Convention
+
+All task files MUST be Markdown (`.md`). The naming schema is strict and must
+follow this exact format:
+
+`YYYY-MMDD.[sequence].[agent].[type].[scope].[short-description]-[HHMM].md`
+
+- **`YYYY-MMDD`**: The 4-digit year, a single hyphen, and the 4-digit month/day
+  (e.g., `2026-0820`).
+- **`[sequence]`**: A 2-digit zero-padded number for the session's file order
+  (e.g., `01`, `02`).
+- **`[agent]`**: The 3-letter author abbreviation (e.g., `jul`, `gem`, `tyl`).
+- **`[type]`**: The work category, matching conventional commits (e.g., `story`,
+  `audit`, `fix`, `feat`, `sec`).
+- **`[scope]`**: The specific architectural boundary or target component (e.g.,
+  `setup-ts`, `auth-api`).
+- **`[short-description]-[HHMM]`**: A kebab-case title followed by a single
+  hyphen and a 4-digit timestamp (hour and minute, e.g., `1702`) to guarantee no
+  filename collisions during simultaneous sessions.
+
+**Example:** `2026-0820.01.jul.feat.auth-api.add-rate-limiting-1702.md`
+
+## B. The Task Lifecycle (Kanban)
+
+Task status is determined **strictly by the file's directory location**, NOT its
+name.
+
+- Files must **never** be renamed once created to preserve links and history.
+- Files should **only** be moved at the absolute end of a work session.
+
+The directories and their purposes are:
+
+- **`tasks/new/`**: Where new tasks are generated. Work begins while the file
+  remains in this folder.
+- **`tasks/wip/`**: This is strictly a parking lot. A file is only moved here at
+  the end of a session if the task could not be completed.
+- **`tasks/complete/`**: Where the file is moved at the end of a session once
+  the work is successfully finished or the PR is merged.
+
+## C. The Required Metadata Header
+
+Every task markdown file must begin with this exact header structure:
+
+```markdown
+# TASK METADATA
+
+- **Target Files:** [List of files involved]
+- **Core Objective:** [1-sentence goal]
+- **Dependencies:** [List any prerequisites or blockers]
+- **Additional Important Notes:** [Any specific constraints, warnings, or
+  context]
+
+---
+```
+
+## D. Mandatory Task File Structure
+
+Every technical story or feature task file MUST include the following sections
+in this exact order:
+
+### 1. TASK METADATA
+
+The YAML/header block containing Target Files, Core Objective, Dependencies, and
+Additional Notes.
+
+### 2. Architectural Considerations & Risks
+
+Before detailing any implementation steps, the authoring agent MUST analyze the
+objective against the existing codebase and document:
+
+- **Risks:** Identify any potential regressions, security vulnerabilities, or
+  architectural anti-patterns this task might introduce.
+- **Alternatives:** Explicitly state if a cleaner, more native, or highly
+  modular approach exists compared to the initial request.
+
+### 3. Proposed Implementation
+
+The structured phases, code extraction points, or execution steps required to
+complete the task safely.

tasks/META_PROMPT.md

@@ -0,0 +1,70 @@
+**Intent of this file:** This file is intended for new-task-prompt development
+and orchestrator templates. It is NOT for actual task research and creation. If
+your current job is to create, plan, or format a task file, please refer to
+`tasks/GUIDELINES.md` and ignore the templates in this file.
+
+---
+
+# Orchestrator Meta-Prompts
+
+## 1. Task Planning Template (System Analyst)
+
+_Use this template to instruct an agent (such as Jules) to take a technical
+idea, critically analyze the existing codebase, identify risks/alternatives, and
+draft a compliant task file in `tasks/new/`._
+
+```text
+**Role:** Act as a System Analyst and Solutions Architect. Do not execute code or modify the codebase during this session. Your sole deliverable is to generate a task file in tasks/new/.
+
+**The Objective:** [State exactly what you want to achieve.]
+
+**Suggestions & Initial Thoughts:** 
+*Here is our starting hypothesis. Treat these as ideas to evaluate, not rigid requirements:*
+*   [Suggestion 1]
+*   [Suggestion 2]
+
+**Your Task:** 
+1. Research the codebase and analyze this objective against our current architecture. 
+2. Critically evaluate our suggestions: Do they make technical sense, or is there a cleaner, more native, or more modular approach?
+3. Map out the `Target Files`, prerequisites/dependencies, and explicitly identify potential architectural risks, regressions, or friction.
+4. Draft the task file in `tasks/new/` strictly adhering to the naming conventions, header metadata, and mandatory structure defined in `tasks/GUIDELINES.md`.
+```
+
+---
+
+## 2. Implementation Execution Template (Developer)
+
+_Use this template when ready to command an agent to execute the work outlined
+in an existing task file._
+
+```text
+**Role:** Act as an Implementation Engineer. 
+
+**The Task:** Please review and execute the plan detailed in `[tasks/new/YYYY-MMDD.XX.agent.type.scope.title-HHMM.md]`.
+
+**Directives:**
+1. Follow the strict 4-step state machine (Research -> Implementation -> Quality Gates -> Review).
+2. Apply minimal, pure functional modifications.
+3. Ensure all downstream pipeline steps and context contracts remain intact.
+4. Run all quality gates (`deno fmt`, `deno task lint`, `deno task check`, `deno task test`).
+5. Upon successful completion and verification, update the task status according to `tasks/GUIDELINES.md`.
+```
+
+---
+
+## 3. Pre-PR Quality & Security Audit Template (Auditor)
+
+_Use this template to instruct an agent to perform an exhaustive pre-merge
+audit._
+
+```text
+**Role:** Act as a Senior Security & Quality Assurance Auditor.
+
+**The Scope:** [List recent changes, PR branch, or target components to audit.]
+
+**Your Task:**
+1. Inspect code changes against architectural boundaries.
+2. Verify zero regression in authentication, session management, or RBAC grants.
+3. Confirm all unit and integration tests pass with 0 lint warnings and 0 typecheck errors.
+4. Document findings and generate an audit report if any vulnerabilities or performance bottlenecks are detected.
+```

tasks/new/2026-0821.01.jul.feat.auth-yes.seamless-3rd-party-sso-1609.md

@@ -0,0 +1,46 @@
+# TASK METADATA
+
+- **Target Files:** `auth-yes/server/db.ts`, `auth-yes/server/oidc.ts`,
+  `auth-yes/server/main.ts`, `auth-yes/ui/admin/integrations.tsx` (and related
+  UI files)
+- **Core Objective:** Implement seamless 3rd-party SSO via a Zero-Click OIDC
+  Provider and Traefik ForwardAuth Header injection.
+- **Dependencies:** Core Auth-Yes session mechanisms, Valkey cache, Hono
+  routing, React/JSX for UI.
+- **Additional Important Notes:** Ensure OIDC logic is decoupled from `main.ts`
+  to prevent a monolith. Database migrations are required for OIDC
+  clients/authorization codes.
+
+---
+
+### Phase 2: The Bonus Stage — Seamless 3rd-Party SSO (Gitea, Portainer, etc.)
+
+Your vision for frictionless 3rd-party access without double-logins is
+achievable through two native patterns we can bring directly into auth-yes:
+
+#### 1. The "Zero-Click" OIDC Provider in auth-yes
+
+• Most self-hosted power tools (Gitea, Nextcloud, Grafana, Portainer, Proxmox,
+Vaultwarden) support standard OpenID Connect (OIDC). • When auth-yes exposes
+standard OIDC endpoints (/oauth/authorize, /oauth/token, /oauth/userinfo): • You
+click "Login with Auth-Yes" on Gitea (or configure Gitea for auto-login). •
+Gitea redirects to auth.atyg.org. • Because you already have your .atyg.org
+passkey cookie active, auth-yes instantly authorizes and redirects back in ~10
+milliseconds without presenting any login dialogs. • Gitea automatically creates
+and syncs your account on the fly.
+
+#### 2. Reverse-Proxy Header Authentication (Traefik ForwardAuth)
+
+• Apps like Gitea have native Reverse Proxy Auth
+(ENABLE_REVERSE_PROXY_AUTHENTICATION = true). • When Traefik calls
+/api/forward-auth, auth-yes injects X-Forwarded-User: <username>. Gitea
+immediately trusts the header and logs you in transparently with zero
+interaction.
+
+#### 3. 3rd-Party App Integrations Manager in Admin Console
+
+• We can expand our Application Registry (/admin/apps) with an Integrations
+Catalog (Client IDs, OIDC secrets, callback URLs, and role-mapping presets for
+Gitea, Grafana, Portainer, etc.). • This gives you a single pane of glass to
+manage passkey-secured SSO across your entire self-hosted ecosystem, allowing
+you to optionally bypass Cloudflare Zero Trust popups entirely.