Readme Update

Author: Asaif Ali

README.md

@@ -1,8 +1,10 @@
 # LegacyLens — Agentic Software Modernization
 
-> **Agentic legacy-code migration with program analysis, dependency intelligence, Qdrant-backed retrieval, migration planning, context-grounded conversion, and post-migration release gates.**
+> **Agentic software modernization with program analysis, dependency intelligence, migration planning, context-grounded code conversion, syntax-aware validation, bounded repair, and release gates.**
 
-LegacyLens analyzes a legacy repository, builds a structured representation of its codebase, creates a migration plan, performs context-grounded code transformation, and evaluates the resulting target project with deterministic engineering checks.
+LegacyLens analyzes a legacy repository, builds a structured representation of its codebase, creates a migration plan, performs context-grounded code transformation, validates generated source, and evaluates the resulting target project with deterministic engineering checks.
+
+The conversion path is deliberately hybrid: deterministic repository analysis and validation remain outside the model, while the LLM is used for semantic translation and bounded repair where explicit transformation rules are insufficient.
 
 ## What changed in the portfolio-ready release
 
@@ -37,14 +39,15 @@ Live migration workspace
 
 ### Reliability / release behavior
 
-The migration platform now has stronger failure handling around the hosted LLM gateway and artifact generation:
+The migration platform treats conversion as a verification loop rather than a one-shot generation step:
 
-- Gateway rate-limit failures are surfaced as real migration failures rather than fabricated code.
-- Invalid/empty model output is rejected instead of being treated as generated source.
-- Directory-like output paths are normalized defensively.
-- Release readiness is derived from the post-migration quality gate.
-- A blocked/failed migration can still produce a clearly labeled failure report when no valid migration artifact exists.
-- Hosted execution can use lightweight workflow settings to reduce unnecessary agent-event retention.
+- LLM inference is routed through the shared Portfolio LLM Gateway using a request-scoped JWT.
+- Deterministic repository analysis and validation remain outside the model.
+- Generated source is sanitized and syntax-validated before it is accepted as migrated code.
+- Syntax failures can trigger a bounded, targeted repair pass instead of a full regeneration.
+- Failed conversion steps are propagated as migration failures rather than being counted as successful conversions.
+- Post-migration quality gates determine release readiness.
+- Blocked migrations are surfaced with explicit failure/review states rather than being presented as successful releases.
 
 ## Architecture
 
@@ -55,13 +58,16 @@ Program Analysis
   AST / CTags / dependencies / stack detection
        ↓
 Knowledge Base
-  Qdrant + metadata-aware retrieval
+  analysis + dependency context
        ↓
 Migration Planning
   target architecture + symbol/file mapping
        ↓
 Agentic Conversion
-  context-grounded transformations
+  deterministic rules + context-grounded LLM translation
+       ↓
+Syntax Validation
+  AST / tree-sitter checks + bounded repair
        ↓
 Post-Migration QA
   structural + executable validation
@@ -79,31 +85,35 @@ Migration artifact or failure report
 - Universal CTags symbol extraction
 - File and symbol dependency analysis
 - Technology/framework detection
-- Qdrant-backed analysis retrieval
+- Knowledge-base retrieval over repository analysis and dependency context
 - Planning before conversion
-- Agentic code transformation
+- Agentic code transformation with deterministic conversion guidance
+- Syntax-aware generated-code validation and bounded repair
 - Deterministic post-migration QA
 - Release gates and repair loops
 - Evidence-backed migration reports
 - Ask-the-codebase retrieval over migration artifacts
 
 ## BYOK / shared LLM Gateway
 
-LegacyLens uses the portfolio's shared LLM Gateway for request-scoped inference sessions.
+LegacyLens uses the portfolio's shared LLM Gateway as its inference boundary.
 
 ```text
-Portfolio BYOK
+Portfolio
+      ↓
+Create request-scoped BYOK session
       ↓
-Short-lived gateway session
+Short-lived JWT
       ↓
 LegacyLens
+  X-LLM-Gateway-Token
       ↓
 Portfolio LLM Gateway
       ↓
 Selected provider / model
 ```
 
-Provider credentials remain outside the project frontend/source repository.
+LegacyLens does not use direct provider API keys for inference in the hosted portfolio path. The gateway handles provider/model selection and credential custody.
 
 ## Local development
 
@@ -125,4 +135,4 @@ LegacyLens is a portfolio and engineering demonstration, not a turnkey enterpris
 
 ## Portfolio positioning
 
-**Developer modernization workbench** — program analysis, retrieval-grounded planning, agentic conversion, executable validation, and release-aware migration workflows.
+**Developer modernization workbench** — program analysis, migration planning, context-grounded conversion, syntax-aware validation, bounded repair, executable checks, and release-aware migration workflows.