aelsha-repolantern 1.0.0__tar.gz

aelsha_repolantern-1.0.0/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 AELSHA INNOVATIONS OPC PRIVATE LIMITED
+
+   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.

aelsha_repolantern-1.0.0/NOTICE

@@ -0,0 +1,24 @@
+AELSHA™ RepoLantern
+Copyright 2026 AELSHA INNOVATIONS OPC PRIVATE LIMITED
+
+This product includes model price data from LiteLLM's model_prices_and_context_window.json
+(https://github.com/BerriAI/litellm), MIT License, Copyright (c) 2023 Berri AI.
+It is used only as an unverified fallback for models without a verified price, and is labelled as such.
+
+The offline eval data in repolantern/evals/snapshots/ (used by the release gate and the admin eval lab) holds
+frozen copies of these public repositories, each with its own licence file inside the snapshot:
+- lukeed/clsx (https://github.com/lukeed/clsx, commit 925494cf31): MIT License,
+  Copyright (c) Luke Edwards <luke.edwards05@gmail.com> (lukeed.com).
+- jonschlinkert/is-odd (https://github.com/jonschlinkert/is-odd, commit a80ee0d831): MIT License,
+  Copyright (c) 2015-present, Jon Schlinkert.
+- pallets/itsdangerous (https://github.com/pallets/itsdangerous, commit 672971d66a): BSD 3-Clause License,
+  Copyright 2011 Pallets.
+- rsc/quote (https://github.com/rsc/quote, commit 5d9f230bcf): BSD 3-Clause License,
+  Copyright (c) 2009 The Go Authors. All rights reserved.
+- octocat/Hello-World (https://github.com/octocat/Hello-World, commit 7fd1a60b01): no licence file; the repository
+  is GitHub's sample and its only file is a README containing the text "Hello World!".
+The golden guides in repolantern/evals/golden/ were generated by RepoLantern from these repositories and quote
+short excerpts of them.
+
+AELSHA™, the AELSHA™ logo, AELSHA™ ASTRA and AELSHA™ RepoLantern are trademarks of
+AELSHA INNOVATIONS OPC PRIVATE LIMITED and are not licensed under the Apache License (see TRADEMARKS.md).

aelsha_repolantern-1.0.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: aelsha-repolantern
+Version: 1.0.0
+Summary: AELSHA™ RepoLantern: turn any Git repository into clear documentation for beginners, senior engineers and architects, with your own LLM key.
+Author: AELSHA INNOVATIONS OPC PRIVATE LIMITED
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://repolantern.aelsha.com
+Project-URL: Documentation, https://repolantern.aelsha.com/docs
+Keywords: documentation,llm,git,langgraph,fastapi,code-documentation,bring-your-own-key
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: langchain==1.4.5
+Requires-Dist: langchain-core==1.6.10
+Requires-Dist: langchain-google-genai==4.4.2
+Requires-Dist: langchain-anthropic==1.7.6
+Requires-Dist: langchain-openai==1.7.2
+Requires-Dist: langchain-text-splitters==1.1.3
+Requires-Dist: langgraph==1.2.15
+Requires-Dist: langgraph-checkpoint==4.3.0
+Requires-Dist: langgraph-checkpoint-sqlite==3.1.2
+Requires-Dist: aiosqlite==0.22.1
+Requires-Dist: google-cloud-storage==3.17.0
+Requires-Dist: fastapi==0.143.1
+Requires-Dist: uvicorn[standard]==0.54.0
+Requires-Dist: sse-starlette==3.5.0
+Requires-Dist: pydantic==2.14.1
+Requires-Dist: pydantic-settings==2.16.0
+Requires-Dist: firebase-admin==7.7.0
+Requires-Dist: google-auth==2.62.0
+Requires-Dist: httpx==0.28.1
+Requires-Dist: markdown-it-py==4.2.0
+Requires-Dist: nh3==0.3.7
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: python-docx==1.2.0
+Requires-Dist: python-pptx==1.0.2
+Requires-Dist: weasyprint==70.0
+Requires-Dist: pygments==2.21.0
+Requires-Dist: lizard==1.24.1
+Requires-Dist: pathspec==1.1.1
+Requires-Dist: pillow==13.0.0
+Requires-Dist: langchain-aws==1.8.2
+Requires-Dist: boto3==1.43.114
+Requires-Dist: botocore==1.43.114
+Requires-Dist: mcp==2.3.0
+Requires-Dist: a2a-sdk==1.2.2
+Requires-Dist: opentelemetry-api==1.45.1
+Requires-Dist: opentelemetry-sdk==1.45.1
+Requires-Dist: opentelemetry-exporter-otlp-proto-http==1.45.1
+Requires-Dist: starlette==1.8.0
+Requires-Dist: anyio==4.15.1
+Requires-Dist: httpcore==1.0.9
+Requires-Dist: cryptography==50.0.2
+Dynamic: license-file
+
+# AELSHA™ RepoLantern
+
+**Understand an unfamiliar codebase before you change it.** RepoLantern turns any Git repository into a grounded
+guide for beginners, senior engineers or architects. Every guide includes architecture diagrams and citations to exact
+lines, and every file and code name in it is checked against the code. It runs with your own AI model key; the key is
+never stored.
+
+This package is the command-line tool. It runs the same pipeline as the web app at
+[repolantern.aelsha.com](https://repolantern.aelsha.com), on your own machine.
+
+## Install
+
+You need Python 3.12 or newer, git 2.50.1 or newer, Graphviz (diagrams) and Pango (PDF export):
+
+| System | Command |
+|---|---|
+| macOS | `brew install git graphviz pango pipx` |
+| Debian or Ubuntu | `sudo apt-get install git graphviz libpango-1.0-0 libpangoft2-1.0-0 pipx` |
+| Windows | Use WSL (Ubuntu) and follow the Debian line |
+
+```
+pipx install aelsha-repolantern
+repolantern --version
+```
+
+## Run
+
+Put your key in an environment variable, never on the command line:
+
+```
+export OPENAI_API_KEY=...
+repolantern run https://github.com/octocat/Hello-World --provider openai --model gpt-6-luna --cap 0.50
+```
+
+The run continues only if the estimate's upper end is within `--cap` (US dollars). Otherwise it stops before spending
+anything. The guide, an assessment and a cost report are written to `./out`.
+
+RepoLantern works with Google Gemini, Vertex AI, Anthropic Claude, OpenAI, AWS Bedrock, Microsoft Foundry and any
+OpenAI-compatible service, including free models on OpenRouter at $0. If a model's limit runs out, the run pauses;
+`repolantern resume <job-id>` continues later on the same or another model, without paying twice for finished work.
+
+## Learn more
+
+- [Command-line guide](https://repolantern.aelsha.com/docs/cli): every provider, option and output
+- [Set up your AI provider](https://repolantern.aelsha.com/setup)
+- [How every guide is checked](https://repolantern.aelsha.com/evals) and [security](https://repolantern.aelsha.com/security)
+- Security reports: [security@aelsha.com](mailto:security@aelsha.com)
+
+Built with AELSHA™ ASTRA by AELSHA INNOVATIONS OPC PRIVATE LIMITED. Licensed under the Apache License 2.0.

aelsha_repolantern-1.0.0/PYPI.md

@@ -0,0 +1,49 @@
+# AELSHA™ RepoLantern
+
+**Understand an unfamiliar codebase before you change it.** RepoLantern turns any Git repository into a grounded
+guide for beginners, senior engineers or architects. Every guide includes architecture diagrams and citations to exact
+lines, and every file and code name in it is checked against the code. It runs with your own AI model key; the key is
+never stored.
+
+This package is the command-line tool. It runs the same pipeline as the web app at
+[repolantern.aelsha.com](https://repolantern.aelsha.com), on your own machine.
+
+## Install
+
+You need Python 3.12 or newer, git 2.50.1 or newer, Graphviz (diagrams) and Pango (PDF export):
+
+| System | Command |
+|---|---|
+| macOS | `brew install git graphviz pango pipx` |
+| Debian or Ubuntu | `sudo apt-get install git graphviz libpango-1.0-0 libpangoft2-1.0-0 pipx` |
+| Windows | Use WSL (Ubuntu) and follow the Debian line |
+
+```
+pipx install aelsha-repolantern
+repolantern --version
+```
+
+## Run
+
+Put your key in an environment variable, never on the command line:
+
+```
+export OPENAI_API_KEY=...
+repolantern run https://github.com/octocat/Hello-World --provider openai --model gpt-6-luna --cap 0.50
+```
+
+The run continues only if the estimate's upper end is within `--cap` (US dollars). Otherwise it stops before spending
+anything. The guide, an assessment and a cost report are written to `./out`.
+
+RepoLantern works with Google Gemini, Vertex AI, Anthropic Claude, OpenAI, AWS Bedrock, Microsoft Foundry and any
+OpenAI-compatible service, including free models on OpenRouter at $0. If a model's limit runs out, the run pauses;
+`repolantern resume <job-id>` continues later on the same or another model, without paying twice for finished work.
+
+## Learn more
+
+- [Command-line guide](https://repolantern.aelsha.com/docs/cli): every provider, option and output
+- [Set up your AI provider](https://repolantern.aelsha.com/setup)
+- [How every guide is checked](https://repolantern.aelsha.com/evals) and [security](https://repolantern.aelsha.com/security)
+- Security reports: [security@aelsha.com](mailto:security@aelsha.com)
+
+Built with AELSHA™ ASTRA by AELSHA INNOVATIONS OPC PRIVATE LIMITED. Licensed under the Apache License 2.0.

aelsha_repolantern-1.0.0/README.md

@@ -0,0 +1,181 @@
+[![CI](https://github.com/AELSHA-INNOVATIONS/aelsha-repolantern/actions/workflows/ci.yml/badge.svg)](https://github.com/AELSHA-INNOVATIONS/aelsha-repolantern/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/AELSHA-INNOVATIONS/aelsha-repolantern/badge)](https://securityscorecards.dev/viewer/?uri=github.com/AELSHA-INNOVATIONS/aelsha-repolantern)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
+
+# AELSHA™ RepoLantern
+
+Turn any Git repository into clear documentation, using your own LLM key.
+
+RepoLantern reads a repository, shows you the cost and the data that will leave your machine, and then writes
+documentation for the audience you choose. It is free and public, and your API keys are never stored on our servers.
+
+## What it does
+
+Point RepoLantern at a repository (public, or private with a scoped credential), pick a model provider and key,
+review the estimated cost and what will be sent, and generate. You get guides for developers, senior engineers and
+architects, plus an assessment of the repository's health and readiness.
+
+## Features
+
+- **Three skills**: beginner, senior and architect guides from the same repository
+- **Bring your own model**: Gemini, Vertex, Claude, OpenAI, Bedrock, Foundry or any OpenAI-compatible endpoint
+- **Cost and data review** before anything is sent, with secrets redacted first
+- **Exports** to Markdown, PDF, DOCX and PPTX, plus draw.io diagrams
+- **Q&A** over the repository
+- **Grounding checks**: every guide is checked against the code and scored. Invented file paths and names are
+  detected, citations are resolved to exact lines, text in the repository addressed to AI tools is flagged, and Q&A
+  answers get the same check. The checks were tested on real guides from three models with 77 planted mistakes
+  ([docs/evals.md](docs/evals.md))
+- **Readiness checklist** (deterministic, free): CI, tests, packaging, health route, configuration, logging, pinned
+  dependencies, licence and credentials in code. For AI and agent apps it also covers tracing, evals, guardrails,
+  cost controls, human oversight and an indicative observability stage (1 to 4). Planned: OSV.dev vulnerabilities,
+  licence inventory, complexity hotspots and an AI opportunity map
+- **Settings per model**: thinking level for reading and for writing, temperature and section length, adjusted to
+  what each model supports, even after a switch ([docs/guide.md](docs/guide.md#6-choosing-thinking-temperature-and-length))
+- **Operator health view** from SQLite alone: golden signals, alerts, reader feedback, and job traces exportable as
+  OpenTelemetry spans
+- **Erase** all your data with one call
+- **Crash-resilient runs** that resume where they stopped
+- **Quota handling**: set requests per minute and per day for your model (free-tier presets are included). When a
+  daily allowance runs out, the job pauses with nothing lost. You can continue on any model or provider (Gemini,
+  Vertex, OpenAI, Claude, Bedrock, Foundry) from the next unfinished piece, or add a fallback chain up front
+- **Lower token use**: the repository is analysed once for every audience, results are remembered by content hash,
+  prompt caching is used where it was measured to help (OpenAI explicit breakpoints cut cost by 16% on one live run),
+  reasoning effort is set per stage, and a cost report shows cache hit rates ([docs/guide.md](docs/guide.md#4-keeping-costs-low))
+- **Private repositories** on any Git host over HTTPS
+- **Command-line interface** that runs the same pipeline locally
+
+## Architecture at a glance
+
+| Layer | Technology | Version | Why this choice |
+|---|---|---|---|
+| Language | Python | 3.12 | Mature async support and the widest choice of LLM libraries |
+| Web framework | FastAPI + Uvicorn + sse-starlette | 0.143.1 / 0.54.0 / 3.5.0 | Async-native, pydantic validation, simple SSE |
+| Validation and settings | pydantic + pydantic-settings | 2.14.1 / 2.16.0 | Typed requests, `SecretStr` so keys never print |
+| LLM abstraction | LangChain (`init_chat_model`) + provider packages | 1.4.5 (core 1.6.10); langchain-google-genai 4.4.2; langchain-anthropic 1.7.6; langchain-openai 1.7.2 | One interface for every provider, with no extra proxy |
+| Orchestration | LangGraph + SQLite checkpointer | 1.2.15; checkpoint 4.3.0; checkpoint-sqlite 3.1.2 | Durable `Send` fan-out, `interrupt()` for cost approval, crash-resume |
+| Text processing | langchain-text-splitters, Python `ast`, regex symbol extractors | 1.1.3 | Language-aware chunking; no native code downloaded at runtime |
+| Database | SQLite (WAL, FTS5) + aiosqlite | stdlib / 0.22.1 | Zero cost, single file, full-text search built in |
+| Replication | Litestream | 0.5.17 (pinned in the image) | Streams SQLite to GCS; restore on cold start |
+| Object storage | google-cloud-storage | 3.17.0 | Lease (generation preconditions), docs, archive |
+| Auth | Firebase Auth + firebase-admin | 7.7.0 | Free Google/GitHub sign-in; server-side token check |
+| Outbound HTTP | httpx + httpcore (DNS-pinned backend) | 0.28.1 | SSRF-safe egress for user-supplied hosts |
+| Markdown | markdown-it-py (raw HTML off) + nh3 | 4.2.0 / 0.3.7 | One safe parse for every renderer; allow-list sanitizing |
+| PDF | WeasyPrint (pango) | 70.0 | Paged-media CSS: covers, running headers, TOC page numbers |
+| Word | python-docx | 1.2.0 | Native styles, bookmarks, linked contents |
+| PowerPoint | python-pptx | 1.0.2 | Structured decks with measured text fit |
+| Diagrams | Graphviz `dot` (system) + Mermaid (in Markdown) + draw.io XML | Graphviz from the base image | Deterministic layout from validated JSON |
+| Code highlighting | Pygments | 2.21.0 | Inline styles; no extra fetches |
+| Images | Pillow | 13.0.0 | Logo sanitising, OG images, PNG measurement |
+| Config files | PyYAML | 6.0.3 | Skill and offer definitions (safe_load only) |
+| Frontend | React 19 + TypeScript + Vite (output in `static/public/app`) | 19.3.0 / 8.3.4 | Strict CSP and Trusted Types; no inline script or style |
+| Testing | pytest, pytest-asyncio, Playwright (Python 1.64.0, web app 1.63.0), PyMuPDF, LibreOffice (dev only) | 9.1.1 / 1.4.0 / 1.64.0 and 1.63.0 / 1.28.2 | TDD, async, real browser e2e, visual export review |
+| Static analysis | ruff, bandit, pip-audit (pinned in requirements-dev.txt) | 0.17.0 / 1.9.4 / 2.10.1 | Lint, security lint, dependency CVEs |
+| Hosting | Cloud Run (request-based), Artifact Registry, Cloud Build | n/a | Scale to zero; free tier |
+| Secrets | Cloud Run environment variables from a git-ignored `deploy.env` (no Secret Manager: zero cost) | n/a | Fingerprint key, state-signing key, trace headers |
+
+See [docs/architecture.md](docs/architecture.md) for the full design.
+
+## Documentation map
+
+| Document | What it is |
+|---|---|
+| [docs/README.md](docs/README.md) | Where to start and the reading order: documents first, then code |
+| [docs/code-map.md](docs/code-map.md) | Every source file, what it does and the idea behind it |
+| [docs/architecture.md](docs/architecture.md) | Design, decision log and traceability; the source of truth |
+| [docs/spec.md](docs/spec.md) | Testable requirements; IDs such as `S-25.3` appear in test comments |
+| [docs/evals.md](docs/evals.md) | How grounding and hallucination checks are measured and re-run |
+| [docs/testing.md](docs/testing.md) | Test layers, rules (including no mocks) and the live-run log |
+| [docs/pipelines.md](docs/pipelines.md) | Every pipeline file and every test suite: what runs where, configuration, commands and results |
+| [docs/guide.md](docs/guide.md) | User guide: quotas, costs, thinking settings, deploying your own copy |
+| [docs/ux-design.md](docs/ux-design.md) | Interface and interaction design |
+| [docs/api.md](docs/api.md) | The HTTP API, job events, MCP and A2A; machine-readable contract in [docs/api/openapi.json](docs/api/openapi.json) |
+| [docs/threat-model.md](docs/threat-model.md) | Assets, threats and the controls against them |
+| [docs/infrastructure.md](docs/infrastructure.md) | Production components, the delivery pipeline and what is tested where |
+| [SECURITY.md](SECURITY.md) | Supported versions and how to report a vulnerability |
+| [docs/runbook.md](docs/runbook.md) | Operating the service and handling incidents |
+| [docs/production.md](docs/production.md) | Production as deployed: setup, settings, operations and troubleshooting |
+| [docs/study-guide.md](docs/study-guide.md) | Guided tour of the codebase for new engineers |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Development setup, checks and pull request rules |
+| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Expected behaviour in project spaces |
+| [SUPPORT.md](SUPPORT.md) | Where to ask questions and report bugs |
+| [CHANGELOG.md](CHANGELOG.md) | Notable changes per version |
+| [RELEASING.md](RELEASING.md) | How a version is cut and deployed |
+| [GOVERNANCE.md](GOVERNANCE.md) | Maintainers, contacts and how decisions are made |
+| [TRADEMARKS.md](TRADEMARKS.md) | Use of the AELSHA™ names and logo |
+| [docs/dependency-licences.md](docs/dependency-licences.md) | Licences of every dependency |
+
+## Quick start
+
+Install the command-line tool (available after the first PyPI release; until then use the from-source install below):
+
+```bash
+pipx install aelsha-repolantern
+```
+
+From source, for development and for running the web app locally. Everything below assumes the virtual environment
+is active:
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements-dev.txt
+pip install -e . --no-deps
+# system packages: brew install graphviz pango   (or apt: graphviz libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz0b fonts-dejavu)
+python -m pytest -q
+```
+
+Document a repository from the command line (the key is read from the environment variable you name,
+never from the command line):
+
+```bash
+export RL_LIVE_GEMINI_KEY=...   # your own key
+repolantern run https://github.com/owner/repo --skills beginner --preset gemini_free --rpm 12
+# paused on a quota? continue on another model or provider:
+repolantern resume <job-id> --provider openai --model gpt-6-luna --fallback "" --key-env MY_OPENAI_KEY
+```
+
+Run the web app locally (same origin as the API, the demo model, no keys needed):
+
+```bash
+(cd frontend && npm ci && npm run build)
+D="$HOME/.repolantern-dev"   # keep the data outside ~/Documents: macOS sync services break SQLite's files there
+RL_AUTH_MODE=dev RL_SERVE_STATIC=true RL_DB_PATH="$D/repolantern.db" RL_WORK_DIR="$D/work" \
+  RL_LOCAL_STORE_DIR="$D/objects" uvicorn repolantern.main:app_factory --factory --port 8000
+# open http://127.0.0.1:8000/app/ ; for live reload while editing: (cd frontend && npm run dev) -> :5173
+```
+
+Run `repolantern run --help` for providers, models, limits, cost caps and output options. What to do when a free
+quota runs out is explained in [docs/guide.md](docs/guide.md#2-what-happens-when-my-free-quota-runs-out).
+Testing is described in [docs/testing.md](docs/testing.md); contributions are welcome, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Deployment
+
+`./deploy.sh --project YOUR_PROJECT --admin-emails you@example.com` (read the plan first with `--dry-run`):
+Cloud Run behind Firebase Hosting, about 30 minutes. Step by step in [docs/guide.md](docs/guide.md#9-deploying-your-own-copy).
+
+## Testing and evals
+
+`python -m pytest -q` runs everything offline; `scripts/eval_gate.py` is the quality gate CI and
+`deploy.sh` run. The web app: `cd frontend && npx vitest run && npx playwright test` (a real browser against the real
+server). The public site: edit `site/`, run `python scripts/build_site.py`. How every score is measured, recorded and re-run: [docs/evals.md](docs/evals.md) §10 and
+[docs/testing.md](docs/testing.md).
+
+## Security
+
+Repository code goes only to the model provider you choose. Dependency names go to OSV.dev for vulnerability
+lookups (public repos, or private repos with your consent). Your API keys are never stored on our servers.
+
+To report a vulnerability, email security@aelsha.com and please do not open a public issue.
+See [SECURITY.md](SECURITY.md).
+
+## Licence
+
+Licensed under the [Apache License 2.0](LICENSE). Copyright 2026 AELSHA INNOVATIONS OPC PRIVATE LIMITED.
+The licence covers the code, not the AELSHA™ names and logo: see [TRADEMARKS.md](TRADEMARKS.md).
+
+## Made with RepoLantern by AELSHA™
+
+RepoLantern is built and maintained by [AELSHA™](https://aelsha.com). If you want help with agentic AI, production
+readiness or a private, self-hosted RepoLantern for your organisation, [get in touch](https://aelsha.com/contact).