devtime-ei 0.1.0__tar.gz → 0.1.1__tar.gz

{devtime_ei-0.1.0 → devtime_ei-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devtime-ei
-Version: 0.1.0
+Version: 0.1.1
 Summary: Local-first Engineering Intelligence for software repositories
 Author-email: Aviad Shakargi <aviad94@gmail.com>
 Maintainer-email: Aviad Shakargi <aviad94@gmail.com>
@@ -8,7 +8,7 @@ License: Apache-2.0
 Project-URL: Homepage, https://github.com/Shakargy/devtime
 Project-URL: Repository, https://github.com/Shakargy/devtime
 Project-URL: Issues, https://github.com/Shakargy/devtime/issues
-Project-URL: Release Notes, https://github.com/Shakargy/devtime/releases/tag/v0.1.0
+Project-URL: Release Notes, https://github.com/Shakargy/devtime/releases/tag/v0.1.1
 Project-URL: Demo, https://youtu.be/1Hiu3Y9J_SI
 Keywords: devtools,cli,static-analysis,repository-analysis,engineering-intelligence,local-first
 Classifier: Development Status :: 3 - Alpha
@@ -56,6 +56,22 @@ decision improves understanding.
 
 ## Try DevTime in 60 seconds
 
+```bash
+pipx install devtime-ei
+dtc demo init
+cd devtime-demo-saas
+dtc init
+dtc scan
+dtc concepts
+dtc explain "Billing Webhooks"
+```
+
+The PyPI distribution is `devtime-ei`. The Python package remains `devtime`, and the
+CLI command remains `dtc`. `dtc demo init` copies a small static example repo into
+`./devtime-demo-saas` so you can try DevTime without cloning this repository.
+
+### From source
+
 ```bash
 git clone https://github.com/Shakargy/devtime.git
 cd devtime
@@ -98,27 +114,36 @@ steps) is in **[DEMO_SCRIPT.md](DEMO_SCRIPT.md)**.
 
 ## Why this exists
 
-Git remembers code. It does not remember understanding. It does not tell you why a
-behavior exists, what evidence supports it, or what nobody has decided yet. As AI
-tools generate code faster than teams can review it, that missing understanding
-becomes the bottleneck.
+Git records what changed, but it does not preserve the reasoning behind those
+changes. When you return to a repository - or review one you did not write - you often
+have to reconstruct why a behavior exists, what evidence supports it, and what is
+still uncertain.
 
-DevTime builds evidence-backed repository memory: a local layer that says what a
-repository can prove, and - just as importantly - what it cannot prove yet.
+DevTime builds evidence-backed repository memory: a local layer that helps a
+codebase explain itself from code, tests, configs, routes, and recorded decisions.
+It shows what the repository can support with evidence - and, just as importantly,
+what it cannot support yet.
 
 ## Who it is for
 
-DevTime is for developers reviewing unfamiliar code, teams using AI coding tools, and
-maintainers who want repository understanding to be backed by evidence instead of
-generated summaries.
+DevTime is for people who need to understand a repository from evidence rather than
+memory.
 
-It is useful when you want to ask:
+It is especially useful if you:
 
-- where is authentication actually implemented?
-- what files prove that billing webhooks exist?
-- what is still uncertain?
-- did this diff touch a risky concept?
-- is there a decision explaining this behavior?
+- are onboarding to an unfamiliar codebase and need to understand how a feature is implemented;
+- are reviewing a pull request and want to see what evidence supports a behavior;
+- are returning to a project after weeks or months and cannot remember why something exists;
+- maintain a long-lived project where design decisions are easily lost;
+- want repository understanding to be backed by code and recorded decisions instead of generated summaries.
+
+Questions DevTime helps answer include:
+
+- Where is authentication actually implemented?
+- What files prove that Billing Webhooks exist?
+- What is still uncertain?
+- Did this diff touch a risky concept?
+- Is there a decision explaining this behavior?
 
 ## What DevTime does
 
@@ -185,7 +210,24 @@ step-by-step first run and troubleshooting.
 
 ## Installation
 
-Recommended source install for now:
+Recommended: install from PyPI with [pipx](https://pipx.pypa.io/) so the `dtc`
+command is available on your PATH in an isolated environment:
+
+```bash
+pipx install devtime-ei
+```
+
+Or with pip:
+
+```bash
+pip install devtime-ei
+```
+
+The PyPI distribution is `devtime-ei`. The Python package remains `devtime`, and the
+CLI command remains `dtc`. After installing, run `dtc demo init` to create a local
+example repo to try it on.
+
+### From source
 
 ```bash
 git clone https://github.com/Shakargy/devtime.git
@@ -205,12 +247,6 @@ python -m venv .venv
 pip install -e ".[dev]"
 ```
 
-Planned PyPI install (after the package is published and verified):
-
-```bash
-pipx install devtime
-```
-
 ## Example output
 
 ```

{devtime_ei-0.1.0 → devtime_ei-0.1.1}/README.md

@@ -20,6 +20,22 @@ decision improves understanding.
 
 ## Try DevTime in 60 seconds
 
+```bash
+pipx install devtime-ei
+dtc demo init
+cd devtime-demo-saas
+dtc init
+dtc scan
+dtc concepts
+dtc explain "Billing Webhooks"
+```
+
+The PyPI distribution is `devtime-ei`. The Python package remains `devtime`, and the
+CLI command remains `dtc`. `dtc demo init` copies a small static example repo into
+`./devtime-demo-saas` so you can try DevTime without cloning this repository.
+
+### From source
+
 ```bash
 git clone https://github.com/Shakargy/devtime.git
 cd devtime
@@ -62,27 +78,36 @@ steps) is in **[DEMO_SCRIPT.md](DEMO_SCRIPT.md)**.
 
 ## Why this exists
 
-Git remembers code. It does not remember understanding. It does not tell you why a
-behavior exists, what evidence supports it, or what nobody has decided yet. As AI
-tools generate code faster than teams can review it, that missing understanding
-becomes the bottleneck.
+Git records what changed, but it does not preserve the reasoning behind those
+changes. When you return to a repository - or review one you did not write - you often
+have to reconstruct why a behavior exists, what evidence supports it, and what is
+still uncertain.
 
-DevTime builds evidence-backed repository memory: a local layer that says what a
-repository can prove, and - just as importantly - what it cannot prove yet.
+DevTime builds evidence-backed repository memory: a local layer that helps a
+codebase explain itself from code, tests, configs, routes, and recorded decisions.
+It shows what the repository can support with evidence - and, just as importantly,
+what it cannot support yet.
 
 ## Who it is for
 
-DevTime is for developers reviewing unfamiliar code, teams using AI coding tools, and
-maintainers who want repository understanding to be backed by evidence instead of
-generated summaries.
+DevTime is for people who need to understand a repository from evidence rather than
+memory.
 
-It is useful when you want to ask:
+It is especially useful if you:
 
-- where is authentication actually implemented?
-- what files prove that billing webhooks exist?
-- what is still uncertain?
-- did this diff touch a risky concept?
-- is there a decision explaining this behavior?
+- are onboarding to an unfamiliar codebase and need to understand how a feature is implemented;
+- are reviewing a pull request and want to see what evidence supports a behavior;
+- are returning to a project after weeks or months and cannot remember why something exists;
+- maintain a long-lived project where design decisions are easily lost;
+- want repository understanding to be backed by code and recorded decisions instead of generated summaries.
+
+Questions DevTime helps answer include:
+
+- Where is authentication actually implemented?
+- What files prove that Billing Webhooks exist?
+- What is still uncertain?
+- Did this diff touch a risky concept?
+- Is there a decision explaining this behavior?
 
 ## What DevTime does
 
@@ -149,7 +174,24 @@ step-by-step first run and troubleshooting.
 
 ## Installation
 
-Recommended source install for now:
+Recommended: install from PyPI with [pipx](https://pipx.pypa.io/) so the `dtc`
+command is available on your PATH in an isolated environment:
+
+```bash
+pipx install devtime-ei
+```
+
+Or with pip:
+
+```bash
+pip install devtime-ei
+```
+
+The PyPI distribution is `devtime-ei`. The Python package remains `devtime`, and the
+CLI command remains `dtc`. After installing, run `dtc demo init` to create a local
+example repo to try it on.
+
+### From source
 
 ```bash
 git clone https://github.com/Shakargy/devtime.git
@@ -169,12 +211,6 @@ python -m venv .venv
 pip install -e ".[dev]"
 ```
 
-Planned PyPI install (after the package is published and verified):
-
-```bash
-pipx install devtime
-```
-
 ## Example output
 
 ```

{devtime_ei-0.1.0 → devtime_ei-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devtime-ei"
-version = "0.1.0"
+version = "0.1.1"
 description = "Local-first Engineering Intelligence for software repositories"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -45,7 +45,7 @@ dev = [
 Homepage = "https://github.com/Shakargy/devtime"
 Repository = "https://github.com/Shakargy/devtime"
 Issues = "https://github.com/Shakargy/devtime/issues"
-"Release Notes" = "https://github.com/Shakargy/devtime/releases/tag/v0.1.0"
+"Release Notes" = "https://github.com/Shakargy/devtime/releases/tag/v0.1.1"
 Demo = "https://youtu.be/1Hiu3Y9J_SI"
 
 [project.scripts]
@@ -59,8 +59,15 @@ build-backend = "setuptools.build_meta"
 where = ["src"]
 
 # Non-Python runtime files that ship inside the package (read at runtime).
+# The demo-saas resource is copied out by `dtc demo init`; the leading-dot
+# .devtimeignore is listed explicitly because glob `*` does not match dotfiles.
 [tool.setuptools.package-data]
-devtime = ["db/*.sql", "assets/*"]
+devtime = [
+    "db/*.sql",
+    "assets/*",
+    "resources/demo-saas/**/*",
+    "resources/demo-saas/.devtimeignore",
+]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{devtime_ei-0.1.0 → devtime_ei-0.1.1}/src/devtime/__init__.py

@@ -1,6 +1,6 @@
 """DevTime - local-first Engineering Intelligence for repository memory."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 # Version metadata (Builder Edition, Chapter 20).
 EVIDENCE_MODEL = "2026.06.1"

{devtime_ei-0.1.0 → devtime_ei-0.1.1}/src/devtime/cli.py

@@ -24,9 +24,13 @@ console = Console()
 claim_app = typer.Typer(help="Inspect and govern claims.")
 decision_app = typer.Typer(help="Record human decisions.")
 mcp_app = typer.Typer(help="Local read-only MCP server.")
+demo_app = typer.Typer(
+    help="Create a local copy of the bundled demo repository.", no_args_is_help=True
+)
 app.add_typer(claim_app, name="claim")
 app.add_typer(decision_app, name="decision")
 app.add_typer(mcp_app, name="mcp")
+app.add_typer(demo_app, name="demo")
 
 
 # --------------------------------------------------------------------------- #
@@ -43,6 +47,37 @@ def init() -> None:
     console.print("AI disabled. Cloud disabled. Telemetry off. MCP read-only.")
 
 
+@demo_app.command("init")
+def demo_init(
+    force: bool = typer.Option(
+        False, "--force", help="Replace devtime-demo-saas if it already exists."
+    ),
+) -> None:
+    """Copy the bundled demo repository into ./devtime-demo-saas (static files only)."""
+    from devtime.demo import DEMO_DIR_NAME, DemoExistsError, create_demo
+
+    try:
+        create_demo(Path.cwd(), force=force)
+    except DemoExistsError as exc:
+        console.print(
+            f"[yellow]{DEMO_DIR_NAME}/ already exists[/yellow] at {exc.path}."
+        )
+        console.print(
+            "Use [bold]dtc demo init --force[/bold] to replace it, "
+            "or remove the directory first."
+        )
+        raise typer.Exit(code=1)
+
+    console.print(f"[green]Demo repository created[/green] at ./{DEMO_DIR_NAME}")
+    console.print("")
+    console.print("Next:")
+    console.print(f"  cd {DEMO_DIR_NAME}")
+    console.print("  dtc init")
+    console.print("  dtc scan")
+    console.print("  dtc concepts")
+    console.print('  dtc explain "Billing Webhooks"')
+
+
 @app.command()
 def status() -> None:
     """Show local storage, AI, cloud, telemetry, MCP, and scan status."""

devtime_ei-0.1.1/src/devtime/demo.py

@@ -0,0 +1,75 @@
+"""Bundled demo repository support for `dtc demo init`.
+
+This lets people who installed DevTime from PyPI (`pipx install devtime-ei`) try it
+without cloning the source repository. It copies a small, static example repo that
+ships inside the installed package into the current working directory.
+
+It only copies static files. It never executes code, never installs anything, never
+runs tests or migrations, and never touches the network. Nothing leaves the machine.
+"""
+
+from __future__ import annotations
+
+import shutil
+from importlib import resources
+from pathlib import Path
+
+# Directory name created in the current working directory.
+DEMO_DIR_NAME = "devtime-demo-saas"
+
+# The packaged demo lives at src/devtime/resources/demo-saas/ and ships in the wheel
+# via [tool.setuptools.package-data].
+_RESOURCE_SUBPATH = ("resources", "demo-saas")
+
+# Artifacts that must never end up in a copied demo, stripped defensively after copy.
+_FORBIDDEN_DIRS = {".devtime", ".git", "node_modules", "__pycache__", ".cache"}
+_FORBIDDEN_FILE_SUFFIXES = (".sqlite", ".sqlite3", ".db")
+
+
+class DemoExistsError(Exception):
+    """Raised when the demo directory already exists and force was not requested."""
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        super().__init__(str(path))
+
+
+def packaged_demo_source() -> Path:
+    """Return a filesystem path to the demo directory bundled in the package."""
+    root = resources.files("devtime")
+    source = root.joinpath(*_RESOURCE_SUBPATH)
+    # In a normal wheel/editable install this is already a real path on disk.
+    return Path(str(source))
+
+
+def _strip_forbidden(dest: Path) -> None:
+    """Remove any artifacts that must never be part of a shared demo."""
+    for path in sorted(dest.rglob("*"), reverse=True):
+        if path.is_dir() and path.name in _FORBIDDEN_DIRS:
+            shutil.rmtree(path, ignore_errors=True)
+        elif path.is_file() and path.suffix.lower() in _FORBIDDEN_FILE_SUFFIXES:
+            path.unlink(missing_ok=True)
+
+
+def create_demo(dest_parent: Path, *, force: bool = False) -> Path:
+    """Copy the bundled demo into ``dest_parent/devtime-demo-saas``.
+
+    Writes only inside ``dest_parent``. Returns the created directory path.
+    Raises :class:`DemoExistsError` if the destination exists and ``force`` is False.
+    """
+    dest = dest_parent / DEMO_DIR_NAME
+    if dest.exists():
+        if not force:
+            raise DemoExistsError(dest)
+        shutil.rmtree(dest)
+
+    source = packaged_demo_source()
+    if not source.is_dir():
+        raise FileNotFoundError(f"Bundled demo not found at {source}")
+
+    # as_file guarantees a real filesystem path even if the package were zipped.
+    with resources.as_file(resources.files("devtime").joinpath(*_RESOURCE_SUBPATH)) as src_path:
+        shutil.copytree(src_path, dest)
+
+    _strip_forbidden(dest)
+    return dest

devtime_ei-0.1.1/src/devtime/resources/demo-saas/.devtimeignore

@@ -0,0 +1,23 @@
+# Secrets
+.env
+.env.*
+*.pem
+*.key
+*.p12
+*.pfx
+id_rsa
+id_ed25519
+secrets.*
+credentials.*
+service-account*.json
+
+# Generated
+node_modules/
+dist/
+build/
+coverage/
+.next/
+.cache/
+
+# VCS
+.git/

devtime_ei-0.1.1/src/devtime/resources/demo-saas/README.md

@@ -0,0 +1,5 @@
+# Demo SaaS
+
+A small SaaS app used as a DevTime demo and test target. It includes
+Authentication, Billing Webhooks, Background Jobs, Admin Permissions, and
+Data Export - with one intentionally missing duplicate-delivery test.

devtime_ei-0.1.1/src/devtime/resources/demo-saas/docs/decisions/0001-use-jwt.md

@@ -0,0 +1,15 @@
+# 0001 - Use JWT for authentication
+
+## Status
+Accepted
+
+## Context
+We needed stateless authentication that works across multiple API instances
+without shared session storage.
+
+## Decision
+Use JWT access tokens signed with a server secret, with a 1 hour expiry.
+
+## Consequences
+- No server-side session store required.
+- Token revocation before expiry is not yet solved.

devtime_ei-0.1.1/src/devtime/resources/demo-saas/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "demo-saas",
+  "version": "1.0.0",
+  "description": "Demo SaaS app for DevTime (Builder Edition, Appendix E).",
+  "dependencies": {
+    "express": "^4.19.0",
+    "stripe": "^15.0.0",
+    "jsonwebtoken": "^9.0.0",
+    "bullmq": "^5.0.0",
+    "ioredis": "^5.4.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  }
+}

devtime_ei-0.1.1/src/devtime/resources/demo-saas/src/admin/permissions.ts

@@ -0,0 +1,9 @@
+import { Request, Response, NextFunction } from "express";
+
+export function requireAdmin(req: Request, res: Response, next: NextFunction) {
+  const role = (req as any).role;
+  if (role !== "admin") {
+    return res.status(403).json({ error: "forbidden" });
+  }
+  return next();
+}

devtime_ei-0.1.1/src/devtime/resources/demo-saas/src/auth/login.ts

@@ -0,0 +1,21 @@
+import { Router } from "express";
+import jwt from "jsonwebtoken";
+
+export const authRouter = Router();
+
+authRouter.post("/auth/login", async (req, res) => {
+  const { email, password } = req.body;
+  const user = await findUser(email, password);
+  if (!user) {
+    return res.status(401).json({ error: "invalid_credentials" });
+  }
+  const token = jwt.sign({ sub: user.id }, process.env.JWT_SECRET as string, {
+    expiresIn: "1h",
+  });
+  return res.json({ token });
+});
+
+async function findUser(email: string, password: string) {
+  // Lookup omitted for the demo.
+  return { id: "u_1", email };
+}

devtime_ei-0.1.1/src/devtime/resources/demo-saas/src/auth/middleware.ts

@@ -0,0 +1,16 @@
+import { Request, Response, NextFunction } from "express";
+import { verifyAccessToken } from "./tokens";
+
+export function requireAuth(req: Request, res: Response, next: NextFunction) {
+  const header = req.headers.authorization;
+  if (!header) {
+    return res.status(401).json({ error: "missing_token" });
+  }
+  try {
+    const payload = verifyAccessToken(header.replace("Bearer ", ""));
+    (req as any).userId = payload.sub;
+    return next();
+  } catch {
+    return res.status(401).json({ error: "invalid_token" });
+  }
+}

devtime_ei-0.1.1/src/devtime/resources/demo-saas/src/auth/tokens.ts

@@ -0,0 +1,11 @@
+import jwt from "jsonwebtoken";
+
+export function issueAccessToken(userId: string): string {
+  return jwt.sign({ sub: userId }, process.env.JWT_SECRET as string, {
+    expiresIn: "1h",
+  });
+}
+
+export function verifyAccessToken(token: string): { sub: string } {
+  return jwt.verify(token, process.env.JWT_SECRET as string) as { sub: string };
+}

devtime_ei-0.1.1/src/devtime/resources/demo-saas/src/billing/stripe-webhook.ts

@@ -0,0 +1,25 @@
+import { Router } from "express";
+import Stripe from "stripe";
+import { updateSubscriptionState } from "./subscription-service";
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string);
+export const billingRouter = Router();
+
+billingRouter.post("/api/stripe/webhook", async (req, res) => {
+  const sig = req.headers["stripe-signature"] as string;
+  let event;
+  try {
+    event = stripe.webhooks.constructEvent(
+      (req as any).rawBody,
+      sig,
+      process.env.STRIPE_WEBHOOK_SECRET as string
+    );
+  } catch (err) {
+    return res.status(400).send("invalid_signature");
+  }
+
+  if (event.type === "customer.subscription.updated") {
+    await updateSubscriptionState(event.data.object);
+  }
+  return res.json({ received: true });
+});

devtime_ei-0.1.1/src/devtime/resources/demo-saas/src/billing/subscription-service.ts

@@ -0,0 +1,11 @@
+export async function updateSubscriptionState(subscription: any): Promise<void> {
+  // Maps a Stripe subscription onto local subscription state.
+  const status = subscription.status;
+  const customerId = subscription.customer;
+  await saveSubscription(customerId, status);
+}
+
+async function saveSubscription(customerId: string, status: string) {
+  // Persistence omitted for the demo.
+  return { customerId, status };
+}

devtime_ei-0.1.1/src/devtime/resources/demo-saas/src/export/export-csv.ts

@@ -0,0 +1,14 @@
+import { Router } from "express";
+
+export const exportRouter = Router();
+
+exportRouter.get("/api/export/users.csv", async (req, res) => {
+  const rows = await loadUsers();
+  const csv = rows.map((r) => `${r.id},${r.email}`).join("\n");
+  res.setHeader("Content-Type", "text/csv");
+  return res.send(csv);
+});
+
+async function loadUsers() {
+  return [{ id: "u_1", email: "demo@example.com" }];
+}

devtime_ei-0.1.1/src/devtime/resources/demo-saas/src/jobs/email-worker.ts

@@ -0,0 +1,16 @@
+import { Worker } from "bullmq";
+import IORedis from "ioredis";
+
+const connection = new IORedis(process.env.REDIS_URL as string);
+
+export const emailWorker = new Worker(
+  "emails",
+  async (job) => {
+    await sendEmail(job.data.to, job.data.template);
+  },
+  { connection }
+);
+
+async function sendEmail(to: string, template: string) {
+  return { to, template };
+}

devtime_ei-0.1.1/src/devtime/resources/demo-saas/src/jobs/queues.ts

@@ -0,0 +1,6 @@
+import { Queue } from "bullmq";
+import IORedis from "ioredis";
+
+const connection = new IORedis(process.env.REDIS_URL as string);
+
+export const emailQueue = new Queue("emails", { connection });

devtime_ei-0.1.1/src/devtime/resources/demo-saas/tests/auth-login.test.ts

@@ -0,0 +1,10 @@
+import { issueAccessToken, verifyAccessToken } from "../src/auth/tokens";
+
+describe("auth login", () => {
+  it("issues and verifies a jwt access token", () => {
+    process.env.JWT_SECRET = "test-secret";
+    const token = issueAccessToken("u_1");
+    const payload = verifyAccessToken(token);
+    expect(payload.sub).toBe("u_1");
+  });
+});

devtime_ei-0.1.1/src/devtime/resources/demo-saas/tests/stripe-signature.test.ts

@@ -0,0 +1,8 @@
+describe("stripe webhook signature", () => {
+  it("rejects an invalid stripe signature", async () => {
+    // Verifies the signature-check branch returns 400 on bad signatures.
+    expect(true).toBe(true);
+  });
+});
+
+// NOTE: intentionally missing a duplicate-delivery / retry test.

{devtime_ei-0.1.0 → devtime_ei-0.1.1}/src/devtime_ei.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devtime-ei
-Version: 0.1.0
+Version: 0.1.1
 Summary: Local-first Engineering Intelligence for software repositories
 Author-email: Aviad Shakargi <aviad94@gmail.com>
 Maintainer-email: Aviad Shakargi <aviad94@gmail.com>
@@ -8,7 +8,7 @@ License: Apache-2.0
 Project-URL: Homepage, https://github.com/Shakargy/devtime
 Project-URL: Repository, https://github.com/Shakargy/devtime
 Project-URL: Issues, https://github.com/Shakargy/devtime/issues
-Project-URL: Release Notes, https://github.com/Shakargy/devtime/releases/tag/v0.1.0
+Project-URL: Release Notes, https://github.com/Shakargy/devtime/releases/tag/v0.1.1
 Project-URL: Demo, https://youtu.be/1Hiu3Y9J_SI
 Keywords: devtools,cli,static-analysis,repository-analysis,engineering-intelligence,local-first
 Classifier: Development Status :: 3 - Alpha
@@ -56,6 +56,22 @@ decision improves understanding.
 
 ## Try DevTime in 60 seconds
 
+```bash
+pipx install devtime-ei
+dtc demo init
+cd devtime-demo-saas
+dtc init
+dtc scan
+dtc concepts
+dtc explain "Billing Webhooks"
+```
+
+The PyPI distribution is `devtime-ei`. The Python package remains `devtime`, and the
+CLI command remains `dtc`. `dtc demo init` copies a small static example repo into
+`./devtime-demo-saas` so you can try DevTime without cloning this repository.
+
+### From source
+
 ```bash
 git clone https://github.com/Shakargy/devtime.git
 cd devtime
@@ -98,27 +114,36 @@ steps) is in **[DEMO_SCRIPT.md](DEMO_SCRIPT.md)**.
 
 ## Why this exists
 
-Git remembers code. It does not remember understanding. It does not tell you why a
-behavior exists, what evidence supports it, or what nobody has decided yet. As AI
-tools generate code faster than teams can review it, that missing understanding
-becomes the bottleneck.
+Git records what changed, but it does not preserve the reasoning behind those
+changes. When you return to a repository - or review one you did not write - you often
+have to reconstruct why a behavior exists, what evidence supports it, and what is
+still uncertain.
 
-DevTime builds evidence-backed repository memory: a local layer that says what a
-repository can prove, and - just as importantly - what it cannot prove yet.
+DevTime builds evidence-backed repository memory: a local layer that helps a
+codebase explain itself from code, tests, configs, routes, and recorded decisions.
+It shows what the repository can support with evidence - and, just as importantly,
+what it cannot support yet.
 
 ## Who it is for
 
-DevTime is for developers reviewing unfamiliar code, teams using AI coding tools, and
-maintainers who want repository understanding to be backed by evidence instead of
-generated summaries.
+DevTime is for people who need to understand a repository from evidence rather than
+memory.
 
-It is useful when you want to ask:
+It is especially useful if you:
 
-- where is authentication actually implemented?
-- what files prove that billing webhooks exist?
-- what is still uncertain?
-- did this diff touch a risky concept?
-- is there a decision explaining this behavior?
+- are onboarding to an unfamiliar codebase and need to understand how a feature is implemented;
+- are reviewing a pull request and want to see what evidence supports a behavior;
+- are returning to a project after weeks or months and cannot remember why something exists;
+- maintain a long-lived project where design decisions are easily lost;
+- want repository understanding to be backed by code and recorded decisions instead of generated summaries.
+
+Questions DevTime helps answer include:
+
+- Where is authentication actually implemented?
+- What files prove that Billing Webhooks exist?
+- What is still uncertain?
+- Did this diff touch a risky concept?
+- Is there a decision explaining this behavior?
 
 ## What DevTime does
 
@@ -185,7 +210,24 @@ step-by-step first run and troubleshooting.
 
 ## Installation
 
-Recommended source install for now:
+Recommended: install from PyPI with [pipx](https://pipx.pypa.io/) so the `dtc`
+command is available on your PATH in an isolated environment:
+
+```bash
+pipx install devtime-ei
+```
+
+Or with pip:
+
+```bash
+pip install devtime-ei
+```
+
+The PyPI distribution is `devtime-ei`. The Python package remains `devtime`, and the
+CLI command remains `dtc`. After installing, run `dtc demo init` to create a local
+example repo to try it on.
+
+### From source
 
 ```bash
 git clone https://github.com/Shakargy/devtime.git
@@ -205,12 +247,6 @@ python -m venv .venv
 pip install -e ".[dev]"
 ```
 
-Planned PyPI install (after the package is published and verified):
-
-```bash
-pipx install devtime
-```
-
 ## Example output
 
 ```

{devtime_ei-0.1.0 → devtime_ei-0.1.1}/src/devtime_ei.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 src/devtime/__init__.py
 src/devtime/cli.py
 src/devtime/config.py
+src/devtime/demo.py
 src/devtime/paths.py
 src/devtime/privacy.py
 src/devtime/ai/__init__.py
@@ -36,6 +37,21 @@ src/devtime/output/__init__.py
 src/devtime/output/json_export.py
 src/devtime/output/markdown.py
 src/devtime/output/terminal.py
+src/devtime/resources/demo-saas/.devtimeignore
+src/devtime/resources/demo-saas/README.md
+src/devtime/resources/demo-saas/package.json
+src/devtime/resources/demo-saas/docs/decisions/0001-use-jwt.md
+src/devtime/resources/demo-saas/src/admin/permissions.ts
+src/devtime/resources/demo-saas/src/auth/login.ts
+src/devtime/resources/demo-saas/src/auth/middleware.ts
+src/devtime/resources/demo-saas/src/auth/tokens.ts
+src/devtime/resources/demo-saas/src/billing/stripe-webhook.ts
+src/devtime/resources/demo-saas/src/billing/subscription-service.ts
+src/devtime/resources/demo-saas/src/export/export-csv.ts
+src/devtime/resources/demo-saas/src/jobs/email-worker.ts
+src/devtime/resources/demo-saas/src/jobs/queues.ts
+src/devtime/resources/demo-saas/tests/auth-login.test.ts
+src/devtime/resources/demo-saas/tests/stripe-signature.test.ts
 src/devtime/scanner/__init__.py
 src/devtime/scanner/file_walker.py
 src/devtime/scanner/ignore.py