dlthub-init 0.1.0__tar.gz

dlthub_init-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Report something that isn't working as expected
+title: 'fix: '
+labels: bug
+---
+
+## Description
+
+<!-- What went wrong? A clear, concise summary. -->
+
+## Steps to reproduce
+
+<!-- The exact command(s) and inputs. Include a snippet/output if relevant. -->
+
+```
+uvx dlthub-init <project-dir>
+```
+
+## Expected behavior
+
+<!-- What you expected to happen instead. -->
+
+## Environment
+
+- `dlthub-init` version:
+- OS:
+- Python version:

dlthub_init-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

dlthub_init-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest an improvement or new capability
+title: 'feat: '
+labels: enhancement
+---
+
+## Problem
+
+<!-- What's the motivation? The gap or friction you're hitting. -->
+
+## Proposed behavior
+
+<!-- What should happen instead. Describe the desired UX/flow. -->
+
+## Alternatives considered
+
+<!-- Other approaches you thought about, if any. Delete if not applicable. -->

dlthub_init-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+<!--
+Title: use Conventional Commits — type(scope): description
+  types: feat | fix | chore | bug | improvement
+  scope (optional, kebab-case): cli, scaffold, collisions, minimal-workspace, ...
+  e.g. fix(collisions): never overwrite an existing secrets.toml
+-->
+
+## Overview
+
+<!-- 1–2 sentences: what this PR does and why. Link any issue/thread it resolves, e.g. "Resolves #6". -->
+
+## Changes
+
+<!-- Bullets of what changed. For larger PRs, group by area with a bold lead, e.g. **`cli.py`**: ... -->
+-
+
+## Tests
+
+<!-- How this was verified: new/updated tests, or manual steps. Delete this section if not applicable. -->
+-

dlthub_init-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,97 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  # POSIX runners: Ubuntu + macOS. GNU make is available, so `make ci` runs
+  # the full chain (lint, unit tests, e2e, lock checks, build).
+  posix:
+    name: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev --frozen
+
+      - name: Lint + type-check
+        run: make lint-ci
+
+      - name: Unit tests
+        run: make test
+
+      - name: Integration tests
+        run: make test-integration
+
+      - name: Build wheel
+        run: make build
+
+  # Windows runner: GNU make isn't standard on windows-latest. Invoke each
+  # check directly via uv so the workflow stays portable.
+  windows:
+    name: windows-latest
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev --frozen
+
+      - name: Lint + type-check
+        run: |
+          uv run ruff format --check src tests tests_integration
+          uv run ruff check src tests tests_integration
+          uv run mypy src tests tests_integration
+
+      - name: Unit tests
+        run: uv run python -m unittest discover -s tests -t .
+
+      - name: Integration tests
+        run: uv run python -m unittest discover -s tests_integration -t .
+
+      - name: Build wheel
+        run: uv build
+
+  lock-check:
+    name: uv.lock drift
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Verify lockfile is in sync with pyproject.toml
+        run: make lock-check
+
+      - name: Verify bundled workspace lockfile is in sync with its pyproject.toml
+        run: make scaffold-lock-check

dlthub_init-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+
+# Example workspaces created for testing
+examples/

dlthub_init-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial release: `uvx dlthub-init [dir]` scaffolds a dltHub workspace into a new or existing directory and optionally creates the virtual environment.
+- Non-destructive by default: safe to run in an existing directory. The run stops only if `.dlt/.workspace` already exists (the directory is already a workspace, exit code `2`); any other existing file is left untouched and reported as skipped. `uv.lock` is written only alongside a freshly created `pyproject.toml`. Flags: `--force`, `--merge`, `--no-pyproject`, `--no-gitignore`, `--no-sync`, `--yes`.
+- Bundled minimal workspace with loosened dependency ranges and a committed `uv.lock` for reproducible installs.
+- `uv sync` runs by default behind an interactive confirmation; a failed sync degrades to a warning so the scaffold still succeeds.
+- `make generate-skills` / `update-skills` / `check-skills` populate the root `skills/` directory from the dltHub AI workbench's `init` toolkit, pinned to a `WORKBENCH_REF` commit (with a CI drift guard), mirroring `dlthub-start`'s AI-generation flow.
+- Scaffolded workspaces receive the bundled skills: copied into `.agents/skills/` (the canonical location most agents read) and linked into `.claude/skills/` via relative symlinks (copied on Windows or when symlinks are unavailable). The skills ship in the wheel from the single-source `skills/` directory.

dlthub_init-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to dlthub-init
+
+## Setup
+
+```bash
+make dev
+```
+
+## Checks
+
+```bash
+make fl       # format + lint-fix
+make lint     # ruff + mypy (no writes)
+make test     # unit tests
+make ci       # everything CI runs
+```
+
+## Layout
+
+- `src/dlthub_init/` — the CLI. `cli.py` orchestrates the flow; `scaffold.py`
+  enumerates and writes the payload; `collisions.py` implements the
+  non-destructive write policy.
+- `src/dlthub_init/scaffolds/minimal_workspace/` — the bundled workspace copied
+  into the user's directory.
+- `tests/` — fast unit tests. `tests_integration/` — slow end-to-end tests that
+  invoke the real CLI and `uv sync`.
+
+## The bundled workspace
+
+The scaffold's `pyproject.toml` uses loose dependency ranges; the committed
+`uv.lock` pins exact versions for reproducible installs. After changing the
+scaffold's dependencies, refresh the lock and commit it:
+
+```bash
+make scaffold-lock-upgrade
+```
+
+## Skills
+
+The root `skills/` directory is generated from the dltHub AI workbench's `init`
+toolkit, pinned to a commit. Don't hand-edit `skills/` — change the skills
+upstream, then re-pull.
+
+Knobs in `scripts/generate_skills.py`:
+- `WORKBENCH_BRANCH` — the branch `update-skills` tracks.
+- `WORKBENCH_REF_SHORT` — short commit SHA (the one GitHub shows); override by hand.
+- `WORKBENCH_REF` — full SHA, written automatically from the short one; never hand-edit.
+- `SKILL_TOOLKITS` — which toolkits' skills to include.
+
+```bash
+make update-skills                  # track WORKBENCH_BRANCH's latest commit
+make update-skills REF=<branch|sha> # pin a specific branch tip or commit
+make generate-skills                # rebuild at the pinned short SHA (auto-fills the full SHA)
+make check-skills                   # CI drift guard
+```
+
+To pin a commit by hand, set `WORKBENCH_REF_SHORT` to a short SHA and run
+`make generate-skills` — it resolves and writes the full `WORKBENCH_REF`.
+
+One-off testing without touching the committed pins (env overrides):
+`DLTHUB_WORKBENCH_REPO` (repo URL or local path), `DLTHUB_WORKBENCH_REF`
+(branch/sha to build from), `DLTHUB_SKILL_TOOLKITS` (comma-separated toolkits).
+
+## Code style
+
+Write self-explanatory code. Do not add comments that narrate what the code
+does; reserve comments for the non-obvious *why*.

dlthub_init-0.1.0/LICENSE

@@ -0,0 +1,92 @@
+dltHub License
+
+Copyright 2026 ScaleVector, GmbH. All rights reserved.
+
+
+## Definitions
+
+"Agreement" means the agreement between ScaleVector, GmbH and its affiliates
+(collectively, "dltHub") and you governing the use of dltHub Services, including
+dltHub Platform, as those terms are defined in the applicable dltHub Terms of Use
+available at: https://dlthub.com/terms.
+
+"dltHub Services" means dltHub Platform and any other products or services offered
+by dltHub, as defined in the Agreement.
+
+"Derivative Works" means any work that is based on, incorporates, or is derived
+from the Licensed Materials, including but not limited to code generated with the
+assistance of the Licensed Materials, modified copies, adaptations, and projects
+into which the Licensed Materials is installed or integrated.
+
+"Licensed Materials" means the source code, object code, data, and/or other works,
+including educational materials, to which this license applies.
+
+## Scope of Use
+
+You may view, use, copy, modify, publish, and distribute the Licensed Materials
+solely in connection with dltHub Services under a governing Agreement. Any use of
+the Licensed Materials outside of dltHub Services is not permitted under this
+license.
+
+Without limiting the foregoing, the following are examples of permitted use:
+
+1. Using toolkits and skills provided by dltHub to develop, build, test,
+   and deploy data pipelines on dltHub Platform.
+2. Copying and modifying toolkit code for use exclusively with dltHub Services and on
+   dltHub Services.
+3. Using the Licensed Materials to generate code intended for deployment on dltHub
+   Platform.
+
+The following are examples of uses that are NOT permitted under this license:
+
+1. Using toolkits and skills provided by dltHub to generate code or pipelines for 
+   deployment on a third-party runtime platform or orchestration service that is not
+   part of dltHub Services.
+2. Modifying toolkits to replace, bypass, or substitute components that are part of
+   dltHub services in order to operate within a third-party development environment.
+3. Incorporating the Licensed Materials or Derivative Works into any product or
+   service that competes with the Licensed Materials, or any other dltHub Services.
+4. Providing the Licensed Materials to third parties as part of a hosted or managed
+   service that replicates the functionality of dltHub Services.
+
+Use beyond the scope of this license requires a separate license agreement
+negotiated with dltHub on a case-by-case basis.
+
+
+## Redistribution
+
+Redistribution of the Licensed Materials, with or without modification, is
+permitted provided that this license notice is included in all copies or substantial
+portions of the Licensed Materials. All recipients are bound by the same scope of
+use restrictions set forth in this license.
+
+## Intellectual Property
+
+dltHub retains all right, title, and interest in and to the Licensed Materials as
+originally published.
+
+dltHub waives all intellectual property claims over Derivative Works, provided that:
+
+1. The use of the Licensed Materials complies with the scope of use set forth in
+   this license, and
+2. This license notice is retained in all copies or substantial portions of the
+   Licensed Materials contained within the Derivative Works.
+
+This waiver extends to the Licensed Materials itself as incorporated into Derivative
+Works — you are free to use, modify, and distribute it within your Derivative Works
+without further restriction, subject only to the scope of use and redistribution
+terms above.
+
+
+## Disclaimer and Limitation of Liability
+
+THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITH ALL FAULTS. DLTHUB AND ITS
+LICENSORS DISCLAIM ALL WARRANTIES, WHETHER EXPRESS, IMPLIED, STATUTORY, OR
+OTHERWISE, INCLUDING WITHOUT LIMITATION THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, TITLE, AND NONINFRINGEMENT. DLTHUB AND ITS LICENSORS'
+TOTAL AGGREGATE LIABILITY RELATING TO OR ARISING OUT OF YOUR USE OF OR DLTHUB'S
+PROVISIONING OF THE LICENSED MATERIALS SHALL BE LIMITED TO ONE THOUSAND DOLLARS
+($1,000). IN NO EVENT SHALL DLTHUB OR ITS LICENSORS BE LIABLE FOR ANY LOST PROFITS,
+LOSS OF REVENUE, LOST BUSINESS, COSTS OF COVER OR ANY INCIDENTAL, SPECIAL,
+EXEMPLARY OR PUNITIVE DAMAGES OF ANY KIND OR NATURE IN CONNECTION WITH THIS LICENSE
+OR THE LICENSED MATERIALS.

dlthub_init-0.1.0/Makefile

@@ -0,0 +1,128 @@
+.DEFAULT_GOAL := help
+
+.PHONY: help dev lint lint-fix format format-check fl lint-ci test test-integration build clean-dist publish ci lock-upgrade lock-check scaffold-lock-upgrade scaffold-lock-check generate-skills update-skills check-skills workspace workspace-init
+
+PYTHON_SOURCES := src tests tests_integration scripts
+SCAFFOLD_DIR ?= src/dlthub_init/scaffolds/minimal_workspace
+
+help: ## Show this help message
+	@echo "Available targets:"
+	@grep -E '^[a-zA-Z0-9_.-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-22s\033[0m %s\n", $$1, $$2}'
+
+dev: ## Install dev dependencies
+	uv sync --extra dev
+
+lint: ## Lint with ruff and type-check with mypy
+	uv run ruff check $(PYTHON_SOURCES)
+	uv run mypy $(PYTHON_SOURCES)
+
+lint-fix: ## Lint and autofix with ruff, type-check with mypy
+	uv run ruff check --fix $(PYTHON_SOURCES)
+	uv run mypy $(PYTHON_SOURCES)
+
+format: ## Format with ruff
+	uv run ruff format $(PYTHON_SOURCES)
+
+format-check: ## Check formatting with ruff (no writes)
+	uv run ruff format --check $(PYTHON_SOURCES)
+
+fl: format lint-fix ## Format and lint-fix in one shot
+
+lint-ci: format-check lint ## CI lint workflow (format-check then lint)
+
+test: ## Run unit tests (fast)
+	uv run python -m unittest discover -s tests -t .
+
+test-integration: ## Run e2e integration tests (slow; invokes real CLI + uv sync)
+	uv run python -m unittest discover -s tests_integration -t .
+
+#
+# Manual test workspaces (under examples/, which is gitignored)
+#
+
+WORKSPACE_DIR ?= examples/my-workspace
+
+workspace: dev ## Scaffold a fresh ./$(WORKSPACE_DIR) for eyeballing output (pre-deletes; pass ARGS="--no-sync")
+	@case "$(WORKSPACE_DIR)" in *..*|"") echo "invalid WORKSPACE_DIR: $(WORKSPACE_DIR)"; exit 1;; esac
+	rm -rf -- "$(WORKSPACE_DIR)"
+	uv run dlthub-init "$(WORKSPACE_DIR)" $(ARGS)
+
+WORKSPACE_INIT_DIR ?= examples/init-workspace
+
+workspace-init: dev ## Init in place: make empty ./$(WORKSPACE_INIT_DIR), cd in, run the CLI with no positional (pass ARGS="--no-sync")
+	@case "$(WORKSPACE_INIT_DIR)" in *..*|"") echo "invalid WORKSPACE_INIT_DIR: $(WORKSPACE_INIT_DIR)"; exit 1;; esac
+	rm -rf -- "$(WORKSPACE_INIT_DIR)"
+	mkdir -p -- "$(WORKSPACE_INIT_DIR)"
+	cd "$(WORKSPACE_INIT_DIR)" && "$(CURDIR)/.venv/bin/dlthub-init" $(ARGS)
+
+build: dev ## Build the package wheel
+	uv build
+
+clean-dist: ## Remove dist/ directory
+	-@rm -r dist/
+
+publish: clean-dist build ## Build and publish dlthub-init to PyPI
+	ls -l dist/
+	@bash -c 'read -s -p "Enter PyPI API token: " PYPI_API_TOKEN; echo; \
+	uv publish --token "$$PYPI_API_TOKEN"'
+
+lock-upgrade: ## Upgrade the root uv.lock to the latest deps pyproject.toml allows (PKG=<name> to bump one); review the diff and commit
+	uv lock $(if $(PKG),--upgrade-package $(PKG),--upgrade)
+
+lock-check: ## CI guard: fail if the root uv.lock is out of sync with pyproject.toml
+	@echo "lock-check: checking uv.lock against pyproject.toml…"; \
+	log="$$(mktemp)"; \
+	if uv lock --check >"$$log" 2>&1; then \
+		rm -f "$$log"; \
+		echo "lock-check: OK — uv.lock is in sync with pyproject.toml."; \
+	else \
+		echo "lock-check: FAILED — run 'make lock-upgrade' and commit. uv output:"; \
+		cat "$$log"; rm -f "$$log"; \
+		exit 1; \
+	fi
+
+scaffold-lock-upgrade: ## Re-resolve the bundled workspace uv.lock (PKG=<name> to bump one); review the diff and commit
+	uv lock $(if $(PKG),--upgrade-package $(PKG),--upgrade) --project $(SCAFFOLD_DIR)
+
+scaffold-lock-check: ## CI guard: fail if the bundled workspace uv.lock is out of sync with its pyproject
+	@echo "scaffold-lock-check: checking $(SCAFFOLD_DIR)/uv.lock against its pyproject.toml…"; \
+	log="$$(mktemp)"; \
+	if uv lock --check --project $(SCAFFOLD_DIR) >"$$log" 2>&1; then \
+		rm -f "$$log"; \
+		echo "scaffold-lock-check: OK — uv.lock is in sync with pyproject.toml."; \
+	else \
+		echo "scaffold-lock-check: FAILED — run 'make scaffold-lock-upgrade' and commit. uv output:"; \
+		cat "$$log"; rm -f "$$log"; \
+		exit 1; \
+	fi
+
+#
+# Skills (pulled from the dltHub AI workbench)
+#
+
+generate-skills: ## Populate skills/ from the dltHub AI workbench at the pinned WORKBENCH_REF
+	uv run python scripts/generate_skills.py
+
+update-skills: ## Bump the workbench ref (REF=<sha>, or latest) and regenerate skills/
+	uv run python scripts/update_skills.py $(REF)
+
+check-skills: ## CI guard: fail if skills/ differs from the generated output
+	@echo "check-skills: regenerating skills/ (output hidden unless it fails)…"; \
+	log="$$(mktemp)"; \
+	if ! uv run python scripts/generate_skills.py >"$$log" 2>&1; then \
+		echo "check-skills: generate-skills failed — its output:"; \
+		cat "$$log"; rm -f "$$log"; exit 1; \
+	fi; \
+	rm -f "$$log"; \
+	changed="$$(git status --porcelain -- skills)"; \
+	if [ -z "$$changed" ]; then \
+		echo "check-skills: OK — skills/ is up to date."; \
+	else \
+		echo "check-skills: FAILED — skills/ differs from 'make generate-skills'; regenerate and commit:"; \
+		printf '%s\n' "$$changed" | sed 's/^/    /'; \
+		git --no-pager diff -- skills; \
+		exit 1; \
+	fi
+
+ci: lint-ci test test-integration lock-check scaffold-lock-check check-skills build ## Run all CI checks locally

dlthub_init-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: dlthub-init
+Version: 0.1.0
+Summary: Scaffold a dltHub workspace into a new or existing directory.
+Project-URL: Homepage, https://github.com/dlt-hub/dlthub-init
+Project-URL: Repository, https://github.com/dlt-hub/dlthub-init
+Project-URL: Issues, https://github.com/dlt-hub/dlthub-init/issues
+Author: dltHub
+License: dltHub License
+        
+        Copyright 2026 ScaleVector, GmbH. All rights reserved.
+        
+        
+        ## Definitions
+        
+        "Agreement" means the agreement between ScaleVector, GmbH and its affiliates
+        (collectively, "dltHub") and you governing the use of dltHub Services, including
+        dltHub Platform, as those terms are defined in the applicable dltHub Terms of Use
+        available at: https://dlthub.com/terms.
+        
+        "dltHub Services" means dltHub Platform and any other products or services offered
+        by dltHub, as defined in the Agreement.
+        
+        "Derivative Works" means any work that is based on, incorporates, or is derived
+        from the Licensed Materials, including but not limited to code generated with the
+        assistance of the Licensed Materials, modified copies, adaptations, and projects
+        into which the Licensed Materials is installed or integrated.
+        
+        "Licensed Materials" means the source code, object code, data, and/or other works,
+        including educational materials, to which this license applies.
+        
+        ## Scope of Use
+        
+        You may view, use, copy, modify, publish, and distribute the Licensed Materials
+        solely in connection with dltHub Services under a governing Agreement. Any use of
+        the Licensed Materials outside of dltHub Services is not permitted under this
+        license.
+        
+        Without limiting the foregoing, the following are examples of permitted use:
+        
+        1. Using toolkits and skills provided by dltHub to develop, build, test,
+           and deploy data pipelines on dltHub Platform.
+        2. Copying and modifying toolkit code for use exclusively with dltHub Services and on
+           dltHub Services.
+        3. Using the Licensed Materials to generate code intended for deployment on dltHub
+           Platform.
+        
+        The following are examples of uses that are NOT permitted under this license:
+        
+        1. Using toolkits and skills provided by dltHub to generate code or pipelines for 
+           deployment on a third-party runtime platform or orchestration service that is not
+           part of dltHub Services.
+        2. Modifying toolkits to replace, bypass, or substitute components that are part of
+           dltHub services in order to operate within a third-party development environment.
+        3. Incorporating the Licensed Materials or Derivative Works into any product or
+           service that competes with the Licensed Materials, or any other dltHub Services.
+        4. Providing the Licensed Materials to third parties as part of a hosted or managed
+           service that replicates the functionality of dltHub Services.
+        
+        Use beyond the scope of this license requires a separate license agreement
+        negotiated with dltHub on a case-by-case basis.
+        
+        
+        ## Redistribution
+        
+        Redistribution of the Licensed Materials, with or without modification, is
+        permitted provided that this license notice is included in all copies or substantial
+        portions of the Licensed Materials. All recipients are bound by the same scope of
+        use restrictions set forth in this license.
+        
+        ## Intellectual Property
+        
+        dltHub retains all right, title, and interest in and to the Licensed Materials as
+        originally published.
+        
+        dltHub waives all intellectual property claims over Derivative Works, provided that:
+        
+        1. The use of the Licensed Materials complies with the scope of use set forth in
+           this license, and
+        2. This license notice is retained in all copies or substantial portions of the
+           Licensed Materials contained within the Derivative Works.
+        
+        This waiver extends to the Licensed Materials itself as incorporated into Derivative
+        Works — you are free to use, modify, and distribute it within your Derivative Works
+        without further restriction, subject only to the scope of use and redistribution
+        terms above.
+        
+        
+        ## Disclaimer and Limitation of Liability
+        
+        THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITH ALL FAULTS. DLTHUB AND ITS
+        LICENSORS DISCLAIM ALL WARRANTIES, WHETHER EXPRESS, IMPLIED, STATUTORY, OR
+        OTHERWISE, INCLUDING WITHOUT LIMITATION THE WARRANTIES OF MERCHANTABILITY, FITNESS
+        FOR A PARTICULAR PURPOSE, TITLE, AND NONINFRINGEMENT. DLTHUB AND ITS LICENSORS'
+        TOTAL AGGREGATE LIABILITY RELATING TO OR ARISING OUT OF YOUR USE OF OR DLTHUB'S
+        PROVISIONING OF THE LICENSED MATERIALS SHALL BE LIMITED TO ONE THOUSAND DOLLARS
+        ($1,000). IN NO EVENT SHALL DLTHUB OR ITS LICENSORS BE LIABLE FOR ANY LOST PROFITS,
+        LOSS OF REVENUE, LOST BUSINESS, COSTS OF COVER OR ANY INCIDENTAL, SPECIAL,
+        EXEMPLARY OR PUNITIVE DAMAGES OF ANY KIND OR NATURE IN CONNECTION WITH THIS LICENSE
+        OR THE LICENSED MATERIALS.
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.10
+Requires-Dist: beaupy>=3.9
+Requires-Dist: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dlthub-init (beta)
+
+Scaffold a [dltHub](https://dlthub.com) workspace into a new or existing directory.
+
+`dlthub-init` lays down the files of a minimal dltHub workspace — `pyproject.toml`,
+a locked `uv.lock`, and the `.dlt/` configuration — and optionally creates the
+virtual environment. That is all it does: it does not log in, run a pipeline, or
+install agent toolkits.
+
+Unlike `dlthub-start`, it is safe to run inside an existing repository. It is
+non-destructive by default: it never overwrites your files, and it stops before
+writing anything if a generated path would collide with something already there.
+
+## Usage
+
+```bash
+uvx dlthub-init             # initialize the current directory
+uvx dlthub-init my-workspace  # initialize ./my-workspace
+```
+
+After scaffolding, `dlthub-init` offers to create a virtual environment and
+install dependencies with `uv`.
+
+### Options
+
+| Flag | Effect |
+| --- | --- |
+| `--no-sync` | Scaffold files only; do not create a venv or install dependencies. |
+| `--force` | Overwrite existing generated files (never secrets). |
+| `--merge` | Append missing entries to an existing `.gitignore` instead of skipping it. |
+| `--no-pyproject` | Skip `pyproject.toml`. |
+| `--no-gitignore` | Skip `.gitignore`. |
+| `--verbose`, `-v` | Stream output from `uv`. |
+
+## Collision behavior
+
+`dlthub-init` is safe to run in an existing directory:
+
+- Missing files are **created**.
+- The run stops only if `.dlt/.workspace` already exists — the directory is
+  already a dltHub workspace (override with `--force`).
+- Otherwise existing files are **left alone** and reported as skipped: your
+  `pyproject.toml`, `.dlt/config.toml`, and `.dlt/secrets.toml` are never
+  overwritten, and `.gitignore` is skipped (or **merged** with `--merge`).
+- `uv.lock` is written only when `pyproject.toml` is created, so the lockfile
+  always matches the workspace's dependencies.
+- `--force` overwrites the generated files (never secrets).
+
+## Development
+
+```bash
+make dev      # install dev dependencies
+make lint     # ruff + mypy
+make test     # unit tests
+make ci       # full local CI
+```
+
+The bundled workspace lives in `src/dlthub_init/scaffolds/minimal_workspace`.
+After editing its `pyproject.toml`, run `make scaffold-lock-upgrade` to refresh
+the committed `uv.lock`.