logicfalcon 0.1.1__tar.gz

logicfalcon-0.1.1/.gitignore

@@ -0,0 +1,48 @@
+# Byte-compiled / optimized files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Environment files
+.env
+.env.local
+*.env
+
+# Testing & Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Type checking & Linters
+.mypy_cache/
+.ruff_cache/
+
+# IDE & Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Docker / local data
+data/
+minio-data/
+postgres-data/
+redis-data/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Frontend build & packages
+node_modules/
+dist/
+dist-ssr/
+
+# Backups & scratch
+backups/

logicfalcon-0.1.1/CHANGELOG.md

@@ -0,0 +1,37 @@
+# LogicFalcon / AEGIS AI — Changelog
+
+All notable changes to the LogicFalcon developer platform (powered by AEGIS AI) are documented in this file.
+
+## [0.1.0] — 2026-10-18: LogicFalcon Initial Open-Source Release
+
+Initial public open-source release of **LogicFalcon** under the Apache License 2.0.
+
+### Highlights & Capabilities
+- **Deterministic Static Code Review**: AST-grounded repository intelligence engine for local Git diff analysis.
+- **Multi-Language AST Parsers**: Static symbol and dependency extraction for Python (`PythonASTParser`) and JavaScript/TypeScript (`JavaScriptTypeScriptParser`).
+- **In-Process Security Rules**: Deterministic checks for hardcoded credentials (`SEC-003`), unsafe subprocess calls with `shell=True` (`SEC-002`), arbitrary dynamic execution via `eval`/`exec` (`SEC-001`), insecure pickle deserialization (`SEC-004`), and broad exception suppression (`QUAL-001`).
+- **Reverse Dependency Traversal**: Automated discovery of test files impacted by source modifications.
+- **Unified Developer CLI**: Added `logicfalcon` CLI exposing `review` and `doctor` subcommands.
+- **Backwards Compatibility**: Preserved `aegis` CLI entry point as a drop-in compatibility alias.
+- **Python SDK**: Exported core domain models (`LocalReviewEngine`, `ReviewConfig`, `ReviewReport`, `FindingSeverity`, `AutonomousDebuggingService`) via `logicfalcon`.
+- **Open-Source Licensing**: Released under Apache License 2.0 with inbound=outbound contributor guidelines and separate trademark reservation.
+
+---
+
+## [Unreleased] — 1.0.0-rc1 (AEGIS AI Core)
+
+### Repository Intelligence & AI Code Review Engine
+- **Unified Diff Parsing**: Added pure-Python unified Git diff parser (`packages/review/git/diff_parser.py`) tracking 1-indexed hunk line numbers, additions, deletions, renames, and binary files with bounded memory limits.
+- **AST Symbol Mapping**: Added AST symbol extraction and line-range correlation (`packages/review/analyzer/symbol_mapper.py`) reusing `PythonASTParser`.
+- **Dependency Graph & Affected Tests**: Added static import dependency graph and reverse dependency traversal (`packages/review/analyzer/dependency_graph.py`) to discover test suites affected by diff changes.
+- **Deterministic AST Security Analyzers**: Added in-process AST security rules (`packages/review/adapters/ast_security.py`) for `eval`/`exec` (`SEC-001`), `subprocess(shell=True)` (`SEC-002`), hardcoded credentials (`SEC-003`), insecure pickle deserialization (`SEC-004`), broad exception suppression (`QUAL-001`), and syntax errors (`SEC-005`).
+- **Static Analysis Runner**: Added subprocess runner (`packages/review/adapters/runner.py`) with process group isolation (`start_new_session=True`), environment scrubbing, and `SIGKILL` timeout enforcement.
+- **Bounded AI Review Engine**: Added repository-aware AI reviewer (`packages/review/ai/reviewer.py`) with strict prompt bounds, defensive prompting against prompt injection, LLM Firewall screening, AI Reliability fallback handling, and Pydantic schema validation.
+- **Hallucination Protection**: Validated all AI finding locations against real changed files and line ranges, rejecting fabricated findings.
+- **Database Persistence**: Added `ReviewSessionEntity` and `ReviewFindingEntity` with Alembic migration `0006_code_review_engine.py` and SQLAlchemy 2.0 Async repositories.
+- **Tenant-Scoped API**: Added REST endpoints under `/api/v1/reviews` with tenant isolation (`organization_id`) and RBAC permissions (`PROJECT_WRITE` / `PROJECT_READ`).
+- **GitHub Webhook & PR Publisher**: Added HMAC-SHA256 webhook verifier (`packages/review/github/webhook.py`) with fail-closed production secret enforcement, delivery deduplication, stale-head commit protection, and dry-run safety.
+- **Read-Only CLI**: Added `aegis review` CLI (`packages/review/cli.py`) with text and JSON formats and configurable severity threshold CI exit codes.
+- **Recruiter Demonstration**: Added standalone demonstration script (`scripts/demo_review_engine.py`) for reproducible, zero-credential local evaluations.
+
+For detailed release notes, see [`docs/release/CHANGELOG_CODE_REVIEW.md`](docs/release/CHANGELOG_CODE_REVIEW.md).

logicfalcon-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to LogicFalcon
+
+Thank you for your interest in contributing to **LogicFalcon** (powered by AEGIS AI)! We welcome contributions from developers, researchers, and organizations building AI-assisted software engineering intelligence.
+
+---
+
+## 1. Open Source Licensing of Contributions
+
+LogicFalcon is licensed under the **Apache License 2.0** ([`LICENSE`](LICENSE)).
+
+- **Inbound = Outbound Model:** By submitting a pull request or patch to this repository, you agree that your contributions will be licensed under the terms of the Apache License 2.0.
+- **No Copyright Transfer:** You retain copyright in your original contributions. You are granting a non-exclusive, perpetual, worldwide license under the terms of Apache-2.0.
+- **Right to Contribute:** You represent and warrant that you are the author of the submitted code or have explicit authorization from your employer or copyright owner to submit the work under Apache-2.0.
+
+---
+
+## 2. Code of Conduct & Review Standards
+
+We expect all contributors to maintain a professional, respectful, and constructive environment.
+
+All pull requests undergo code review focusing on:
+- **Correctness and Determinism:** LogicFalcon prioritizes evidence-grounded analysis. Reasoning and code review features must be backed by verifiable AST or graph evidence.
+- **Security & Privacy:** Code review rules and telemetry ingestion must treat user repository data as untrusted. Never log secrets, credentials, or private keys.
+- **Architectural Separation:** Preserve the layered architecture: API routers → application services → domain models → repositories → infrastructure.
+
+---
+
+## 3. How to Submit Issues and Pull Requests
+
+### Reporting Issues
+- Check existing GitHub issues before creating a new report to avoid duplicates.
+- Include Python version, OS platform, and relevant terminal/CLI output.
+- **Security Disclosures:** Do not post suspected security vulnerabilities in public issues. Please report security concerns privately to the project maintainers.
+
+### Pull Request Process
+1. **Fork the Repository:** Create your feature branch from `main`.
+2. **Make Changes:** Keep commits focused, well-structured, and descriptively titled.
+3. **Add Tests:** Every new feature, rule, parser, or bugfix must include unit or integration tests in `tests/`.
+4. **Run Quality Gates:**
+   ```bash
+   # 1. Run linter
+   uv run ruff check .
+
+   # 2. Run static type checker
+   uv run mypy --explicit-package-bases logicfalcon aegis apps packages tests
+
+   # 3. Run test suite
+   uv run pytest tests/
+   ```
+5. **Submit PR:** Open a Pull Request against `main`. Provide a clear summary of the problem addressed, changes introduced, and test results.
+
+---
+
+## 4. Third-Party Code & Dependencies Policy
+
+- **License Compatibility:** Any new third-party dependency or library introduced must be compatible with Apache-2.0 (e.g., Apache-2.0, MIT, BSD-2-Clause, BSD-3-Clause, ISC).
+- **Prohibited Licenses:** Do not introduce copyleft dependencies (GPL, AGPL) or libraries with commercial restriction clauses without explicit maintainer approval.
+- **Preserving Notices:** If you incorporate permitted third-party code snippets or files, you must preserve existing copyright notices, license headers, and disclaimers.
+- **Documenting Dependencies:** All dependencies must be declared in `pyproject.toml` with pinned lower bounds.
+
+---
+
+## 5. Trademark Notice
+
+The **LogicFalcon** name, logo, and brand marks are trademarks of the project authors and are separate from the software copyright license. The Apache-2.0 license grants software usage and modification rights but does not grant unrestricted trademark rights to use the LogicFalcon brand marks without permission.

logicfalcon-0.1.1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 LogicFalcon Authors & Contributors (powered by AEGIS AI)
+
+   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
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

logicfalcon-0.1.1/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.5
+Name: logicfalcon
+Version: 0.1.1
+Summary: LogicFalcon — Fast, precise engineering intelligence. Powered by AEGIS AI.
+Project-URL: Homepage, https://github.com/Livesh-L-28/logicfalcon
+Project-URL: Documentation, https://github.com/Livesh-L-28/logicfalcon#readme
+Project-URL: Repository, https://github.com/Livesh-L-28/logicfalcon.git
+Project-URL: Issues, https://github.com/Livesh-L-28/logicfalcon/issues
+Author: LogicFalcon Team (powered by AEGIS AI)
+License: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Requires-Dist: aiobotocore>=2.13.0
+Requires-Dist: aireliability>=0.1.0
+Requires-Dist: alembic>=1.13.1
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: greenlet>=3.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: llmfirewall-core>=1.0.0
+Requires-Dist: opentelemetry-api>=1.25.0
+Requires-Dist: opentelemetry-exporter-otlp>=1.25.0
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.46b0
+Requires-Dist: opentelemetry-sdk>=1.25.0
+Requires-Dist: pgvector>=0.2.5
+Requires-Dist: prometheus-client>=0.20.0
+Requires-Dist: pydantic-settings>=2.2.1
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: python-json-logger>=2.0.7
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: redis>=5.0.4
+Requires-Dist: sqlalchemy[asyncio]>=2.0.30
+Requires-Dist: structlog>=24.1.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.20.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.6; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.2.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.4; extra == 'dev'
+Requires-Dist: types-redis>=4.6.0.20240425; extra == 'dev'
+Provides-Extra: packaging
+Requires-Dist: build>=1.2.0; extra == 'packaging'
+Requires-Dist: twine>=5.0.0; extra == 'packaging'
+Description-Content-Type: text/markdown
+
+# LogicFalcon — Fast, precise engineering intelligence.
+
+> **LogicFalcon, powered by AEGIS AI**  
+> LogicFalcon is an AI-powered software engineering intelligence platform for evidence-grounded code review, repository analysis, change-impact assessment, root-cause analysis, and safe fix proposals. Powered by AEGIS AI.
+
+---
+
+## Quickstart & Installation
+
+### 1. Installation via pip
+
+```bash
+pip install logicfalcon
+```
+
+### 2. Developer CLI Usage
+
+```bash
+# Verify environment and AST analyzer capabilities
+logicfalcon doctor
+
+# Run deterministic code review on local git diff
+logicfalcon review --repo .
+
+# Machine-readable JSON output for CI pipelines
+logicfalcon review --repo . --format json --severity-threshold ERROR
+```
+
+### 3. Python SDK Usage
+
+```python
+from pathlib import Path
+from logicfalcon import LocalReviewEngine, ReviewConfig
+
+config = ReviewConfig(
+    max_file_size_bytes=1_000_000,
+    per_file_timeout_seconds=10.0,
+    enable_ai_review=False,  # Deterministic static analysis by default
+)
+engine = LocalReviewEngine(repo_root=Path("."), config=config)
+report = engine.review_local_git_diff()
+print(f"Scanned {len(report.files_reviewed)} files. Found {len(report.findings)} issues.")
+```
+
+---
+
+## Platform Engine (AEGIS AI Foundation)
+
+LogicFalcon's core reasoning, multi-language AST comprehension, and autonomous reliability engines are built on the **AEGIS AI** platform architecture.
+
+> **Engine Status: Phase 7 — Autonomous Reliability + Evaluation + Production Hardening COMPLETE (CURRENT)**
+
+> **Phase 7 Scope Note:** Phase 7 concludes the roadmap by delivering bounded autonomous reliability under deterministic safety controls: bounded agent execution loops with strict tool and cost budgets, multi-tiered autonomy levels (`LEVEL_0` through `LEVEL_3`), emergency stop kill switches, change freeze mechanisms, autonomy circuit breakers, continuous evaluation against golden and adversarial datasets with strict release gates, SLO and error budget tracking, and operational learning from validated incidents without self-modifying code or policies.
+
+
+---
+
+## Unified System Model
+
+```text
+                    AEGIS INTELLIGENCE
+                           │
+          ┌────────────────┼────────────────┐
+          │                │                │
+          ▼                ▼                ▼
+      SYSTEM            CODE            KNOWLEDGE
+   INTELLIGENCE      INTELLIGENCE      INTELLIGENCE
+          │                │                │
+          ▼                ▼                ▼
+      Services          Git             Docs
+      Dependencies      Files           Runbooks
+      Environments      Symbols         Incidents
+      Deployments       Commits         Postmortems
+      Telemetry         AST             Architecture
+          │                │                │
+          └────────────────┼────────────────┘
+                           ▼
+                  UNIFIED SYSTEM MODEL
+```
+
+---
+
+## Intelligence Capabilities
+- **System Intelligence**: Runtime topology discovery, typed dependency relationships (`HTTP`, `DATABASE`, `CACHE`), machine-readable graph API (`GET /api/v1/intelligence/dependency-graph`).
+- **Code Intelligence**: Static AST parsing (classes, methods, functions, signatures, docstrings, imports), SHA256 incremental indexing, secret redaction (`[REDACTED_SECRET]`), symbol search (`POST /api/v1/intelligence/code/search`).
+- **Knowledge Intelligence**: Section-based document chunking, 64-dimensional unit vector embeddings, hybrid keyword + dense vector retrieval with score normalization (`POST /api/v1/intelligence/knowledge/search`).
+- **Unified Context API**: Assembles full service context across topology, symbols, and operational documentation (`GET /api/v1/intelligence/services/{service}/context`).
+
+---
+
+## Public Portfolio Architecture (Render All-in-One Deployment)
+
+```text
+                               GitHub Repository
+                                       │
+                      ┌────────────────┴────────────────┐
+                      ▼                                 ▼
+           Render Static Site                  Render Web Service
+        React 18 + Vite Frontend               FastAPI Backend API
+        (aegis-ai-web.onrender.com)        (aegis-ai-api.onrender.com)
+                      │                                 │
+                      │  (REST API & SSE stream)        │
+                      └────────────────►────────────────┤
+                                                        │
+                                     ┌──────────────────┼──────────────────┐
+                                     ▼                  ▼                  ▼
+                                Render Postgres       Redis          Object Storage
+                                  + pgvector    (Upstash / Aiven)   (Cloudflare R2 / S3)
+```
+
+---
+
+## Live Demo & Documentation
+
+### Deployed Portfolio URLs
+
+* **Deployment Documentation**: [`docs/deployment/public-demo.md`](docs/deployment/public-demo.md)
+* **Render Blueprint**: [`render.yaml`](render.yaml) (1-Click deployment for Frontend + Backend + PostgreSQL)
+* **Frontend**: Configured for Render Static Site (`apps/web`, SPA rewrite `/* -> /index.html`, `VITE_API_BASE_URL`) or Vercel
+* **API**: Configured for Render Docker Web Service with dynamic `$PORT` and container health checks
+
+---
+
+## Local Quickstart (Full Docker Compose Environment)
+
+To run the complete AEGIS ecosystem locally including Prometheus, Grafana, Loki, MinIO, and 4 simulated microservices:
+
+```bash
+# 1. Clone repository
+git clone <repository_url>
+cd "AEGIS AI"
+
+# 2. Configure environment
+cp .env.example .env
+
+# 3. Start complete local infrastructure
+docker compose up --build -d
+
+# 4. Open Command Center
+open http://localhost:5173
+```
+
+---
+
+## Interactive Recruiter Demo Scenario
+
+Experience the complete **Observe → Reason → Propose → Approve → Sandbox Execute → Validate** autonomous reliability lifecycle:
+
+1. **Open Dashboard**: Navigate to the Operational Overview.
+2. **Trigger Incident (INC-001)**: Under *Canonical Fault Scenarios*, click **Inject Fault** on scenario `SCEN-001` (Redis Connection Exhaustion) or `SCEN-002` (Downstream Latency Spike).
+3. **Observe Incident**: View the newly detected incident in the *Live Incident Pipeline* with its severity and affected service.
+4. **Run AI Investigation**: Click **Investigate** to open the Incident Deep Dive. Click **Run AI Investigation** to correlate telemetry, git history, and runbooks.
+5. **Inspect Evidence & Causal Graph**: Review multi-modal evidence signals and the determined root cause.
+6. **Propose Remediation**: Click **Propose AI Remediation** to synthesize a bounded, typed action plan.
+7. **Review Risk & Blast Radius**: Inspect calculated risk levels and affected services.
+8. **Human Approval**: Click **Approve Action** to cryptographically authorize the plan.
+9. **Sandbox Execution**: Click **Execute in Sandbox** to safely apply the fix to the simulated environment.
+10. **Validate & Audit**: Inspect the automated post-flight verification check and the immutable entry recorded in the Audit log.
+
+---
+
+## Verification & Quality Gates
+
+```bash
+# Code formatting & lint check
+uv run ruff check .
+
+# Strict static type check
+uv run mypy --explicit-package-bases logicfalcon aegis apps packages tests
+
+# Automated test suite
+uv run pytest tests/ -q
+```
+
+---
+
+## License & Trademarks
+
+- **Software License**: LogicFalcon is open-source software licensed under the **Apache License, Version 2.0**. See the authoritative license terms in [`LICENSE`](LICENSE).
+- **Platform Foundation**: LogicFalcon is powered by the **AEGIS AI** engineering intelligence platform.
+- **Copyright & Attribution**: Copyright 2026 LogicFalcon Authors & Contributors (powered by AEGIS AI). Third-party dependencies retain their respective permissive licenses (MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause).
+- **Trademarks**: The LogicFalcon name and logo are product brand identifiers separate from the software copyright license and are not licensed for unrestricted trademark use.
+- **Contributing**: Contributions are subject to the terms in [`CONTRIBUTING.md`](CONTRIBUTING.md).
+