container-superposition 0.1.5 → 0.1.7

package/docs/overlay-imports.md

@@ -4,25 +4,28 @@ Overlays can import shared configuration fragments from `overlays/.shared/` to r
 
 ## Overview
 
-Import functionality allows overlays to reference common configuration files instead of duplicating them in every overlay. This promotes DRY (Don't Repeat Yourself) principles and makes it easier to maintain consistent patterns.
+The import mechanism allows overlays to reference common configuration files instead of duplicating them. This promotes DRY principles and makes it easier to maintain consistent patterns.
+
+Imports are declared in the overlay's `overlay.yml` manifest and applied **before** the overlay's own `devcontainer.patch.json`, so each overlay can specialize on top of a shared baseline.
 
 ## Shared Directory Structure
 
 ```
 overlays/
 ├── .shared/
-│   ├── otel/                           # OpenTelemetry configurations
-│   │   ├── otel-base-config.yaml      # Base OTEL collector config
-│   │   └── instrumentation.env        # Common env vars for instrumentation
-│   ├── compose/                        # Docker Compose patterns
-│   │   └── common-healthchecks.yml    # Standard healthcheck configurations
-│   └── vscode/                         # VS Code extension sets
-│       └── recommended-extensions.json # Commonly recommended extensions
+│   ├── README.md
+│   ├── otel/
+│   │   ├── instrumentation.env        # OTEL SDK env vars — imported by otel-collector, prometheus, jaeger
+│   │   └── otel-base-config.yaml      # Base OTEL collector pipeline config
+│   ├── compose/
+│   │   └── common-healthchecks.yml    # Standard Docker Compose healthcheck patterns
+│   └── vscode/
+│       └── recommended-extensions.json # Commonly recommended VS Code extensions (devcontainer patch format)
 ├── prometheus/
-│   ├── overlay.yml                     # Can import from .shared/
+│   ├── overlay.yml                    # imports: [.shared/otel/instrumentation.env]
 │   └── devcontainer.patch.json
 └── jaeger/
-    ├── overlay.yml                     # Can import from .shared/
+    ├── overlay.yml                    # imports: [.shared/otel/instrumentation.env]
     └── devcontainer.patch.json
 ```
 
@@ -48,101 +51,128 @@ ports:
     - 9090
 imports:
     - .shared/otel/instrumentation.env
-    - .shared/compose/common-healthchecks.yml
 ```
 
-## Supported File Types
+**Rules:**
+
+- All paths **must** begin with `.shared/` — references outside `.shared/` are rejected (path traversal prevention)
+- Paths are relative to `overlays/`
+- Order is significant — fragments are applied in declaration order, then the overlay's own `devcontainer.patch.json`
+- Missing files, unsupported types, or path traversal attempts cause generation to fail with a message identifying the overlay and the broken reference
 
-### JSON Files (`.json`)
+## Supported File Types and Merge Behavior
 
-Merged as devcontainer patches, just like `devcontainer.patch.json`.
+| Extension        | How it is merged                                                               |
+| ---------------- | ------------------------------------------------------------------------------ |
+| `.json`          | Deep-merged into `devcontainer.json` patch (same as `devcontainer.patch.json`) |
+| `.yaml` / `.yml` | Loaded and deep-merged into `devcontainer.json` patch                          |
+| `.env`           | Concatenated into `.env.example` with a `# from .shared/…` comment header      |
+| Anything else    | Rejected with a clear unsupported-type error                                   |
 
-**Example: `.shared/vscode/recommended-extensions.json`**
+### JSON import example
 
-```json
+```jsonc
+// overlays/.shared/vscode/recommended-extensions.json
 {
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
     "customizations": {
         "vscode": {
             "extensions": [
                 "streetsidesoftware.code-spell-checker",
                 "usernamehw.errorlens",
-                "editorconfig.editorconfig"
-            ]
-        }
-    }
+                "eamodio.gitlens",
+            ],
+        },
+    },
 }
 ```
 
-### YAML Files (`.yaml`, `.yml`)
-
-Loaded and merged as devcontainer patches. Useful for complex configurations.
-
-**Example: `.shared/otel/otel-base-config.yaml`**
+### YAML import example
 
 ```yaml
-receivers:
-    otlp:
-        protocols:
-            grpc:
-                endpoint: 0.0.0.0:4317
-            http:
-                endpoint: 0.0.0.0:4318
+# overlays/.shared/otel/otel-base-config.yaml
+remoteEnv:
+    OTEL_SERVICE_NAME: my-service
+    OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4317
 ```
 
-### Environment Files (`.env`)
+### ENV import example
 
-Merged into `.env.example` with a comment indicating the import source.
+```bash
+# overlays/.shared/otel/instrumentation.env
+# OpenTelemetry SDK Configuration
+OTEL_SERVICE_NAME=my-service
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
+OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+OTEL_TRACES_SAMPLER=always_on
+OTEL_TRACES_EXPORTER=otlp
+OTEL_METRICS_EXPORTER=otlp
+OTEL_LOGS_EXPORTER=otlp
+```
 
-**Example: `.shared/otel/instrumentation.env`**
+When this `.env` fragment is imported, the generated `.env.example` will contain:
 
 ```bash
-# OpenTelemetry Configuration
+# from .shared/otel/instrumentation.env
 OTEL_SERVICE_NAME=my-service
 OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
-OTEL_TRACES_SAMPLER=always_on
+...
 ```
 
-## How Imports Work
+## Import Ordering and Conflict Resolution
 
-1. **Resolution**: Imports are resolved relative to the `overlays/` directory
-2. **Order**: Imports are applied in the order listed, then the overlay's own files
-3. **Merging**:
-    - JSON/YAML: Deep merged into devcontainer configuration
-    - ENV: Concatenated into `.env.example` with source comments
-4. **Validation**: Doctor command validates that all imports exist and are valid
+Imports are applied in declaration order, then the overlay's own `devcontainer.patch.json` is applied last:
 
-## Benefits
+```
+[import 1] → [import 2] → … → [import N] → [overlay own patch]
+```
 
-### Reduced Duplication
+- The **second** import wins over the first on key conflict
+- The **overlay's own patch always wins** over any shared fragment
 
-Before imports:
+This means overlays can intentionally override shared defaults by setting the same key in their `devcontainer.patch.json`.
 
-```
-prometheus/devcontainer.patch.json  (200 lines with OTEL config)
-jaeger/devcontainer.patch.json      (200 lines with OTEL config)
-grafana/devcontainer.patch.json     (200 lines with OTEL config)
+## Worked Example: OTEL Instrumentation
+
+Many observability overlays need OTEL environment variables. With imports, these are defined once:
+
+**`overlays/.shared/otel/instrumentation.env`** — shared once
+
+**`overlays/otel-collector/overlay.yml`:**
+
+```yaml
+imports:
+    - .shared/otel/instrumentation.env
 ```
 
-After imports:
+**`overlays/prometheus/overlay.yml`:**
 
+```yaml
+imports:
+    - .shared/otel/instrumentation.env
 ```
-.shared/otel/otel-base-config.yaml  (50 lines, shared)
-prometheus/overlay.yml              (imports: [.shared/otel/otel-base-config.yaml])
-jaeger/overlay.yml                  (imports: [.shared/otel/otel-base-config.yaml])
-grafana/overlay.yml                 (imports: [.shared/otel/otel-base-config.yaml])
+
+**`overlays/jaeger/overlay.yml`:**
+
+```yaml
+imports:
+    - .shared/otel/instrumentation.env
 ```
 
-### Consistency
+When any of these overlays is used, the generated `.env.example` will contain the OTEL environment variables with a comment indicating they came from the shared fragment.
+
+## Security: Path Traversal Prevention
 
-All overlays using the same shared config stay in sync automatically.
+Import paths are validated before any file is read:
 
-### Maintainability
+1. The path **must** begin with `.shared/`
+2. The resolved absolute path **must** remain inside `overlays/.shared/`
 
-Update shared configuration once, all importing overlays benefit.
+Any import that fails either check causes generation to abort with an error identifying the overlay and the rejected path. References like `../secret.json`, `/etc/passwd`, or `other-overlay/file.json` are all rejected.
 
-## Validation
+## Validation via Doctor
 
-The `doctor` command validates imports:
+The `doctor` command validates all imports for every overlay:
 
 ```bash
 container-superposition doctor
@@ -150,60 +180,53 @@ container-superposition doctor
 
 Checks performed:
 
-- Import files exist
-- File types are supported (`.json`, `.yaml`, `.yml`, `.env`)
-- No broken import references
-
-## Creating Shared Configurations
-
-1. **Identify common patterns** across overlays
-2. **Extract to `.shared/` subdirectory** with descriptive path
-3. **Update overlays** to import the shared file
-4. **Test** that composition works correctly
-5. **Document** the shared file's purpose in `.shared/README.md`
+- Import path starts with `.shared/` (path traversal check)
+- Import path resolves within `overlays/.shared/` (traversal check)
+- Import file exists on disk
+- File type is one of `.json`, `.yaml`, `.yml`, `.env`
 
-## Example: OTEL Instrumentation
+Broken references are reported with the overlay ID and the bad path so maintainers can fix them quickly.
 
-Many observability overlays need OTEL instrumentation. Instead of duplicating these environment variables:
+## Viewing Imports in `explain`
 
-**Create:** `overlays/.shared/otel/instrumentation.env`
+When an overlay has imports, they are shown in the `explain` output:
 
 ```bash
-# OpenTelemetry SDK Configuration
-OTEL_SERVICE_NAME=my-service
-OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
-OTEL_EXPORTER_OTLP_PROTOCOL=grpc
-OTEL_RESOURCE_ATTRIBUTES=deployment.environment=development
-OTEL_TRACES_SAMPLER=always_on
-OTEL_TRACES_EXPORTER=otlp
-OTEL_METRICS_EXPORTER=otlp
-OTEL_LOGS_EXPORTER=otlp
+container-superposition explain prometheus
 ```
 
-**Import in overlays:**
+```
+Shared Imports:
+  (Fragments from overlays/.shared/ applied before this overlay)
+  📎 .shared/otel/instrumentation.env
+```
 
-```yaml
-# overlays/prometheus/overlay.yml
-imports:
-    - .shared/otel/instrumentation.env
+## Creating Shared Configurations
 
-# overlays/jaeger/overlay.yml
-imports:
-    - .shared/otel/instrumentation.env
-```
+1. **Identify common patterns** across multiple overlays
+2. **Create `overlays/.shared/<category>/<name>.<ext>`** — use descriptive paths, one concern per file
+3. **Update overlays** to reference the fragment via `imports:` in their `overlay.yml`
+4. **Update `.shared/README.md`** to document the fragment's purpose and which overlays use it
+5. **Test** with `npm test` and `container-superposition doctor` to verify
+
+## Downstream Impact Awareness
+
+A single change to a shared fragment affects every overlay that imports it. Before editing a shared fragment:
 
-Now all OTEL-compatible overlays share the same instrumentation configuration!
+- Check `.shared/README.md` to see which overlays import it
+- Use `grep -r "fragment-name" overlays/*/overlay.yml` to find all importers
+- Run the full test suite after any shared fragment change
 
 ## Best Practices
 
-1. **Keep shared files focused** - One concern per file
-2. **Use descriptive paths** - `.shared/otel/instrumentation.env` not `.shared/env1.env`
-3. **Document shared files** - Add comments explaining purpose and usage
-4. **Version carefully** - Changes to shared files affect all importing overlays
-5. **Test imports** - Verify overlay composition works after adding imports
+1. **One concern per file** — `instrumentation.env` not `all-the-things.env`
+2. **Descriptive category paths** — `.shared/otel/` not `.shared/misc/`
+3. **Comment your fragments** — explain purpose and usage at the top of each file
+4. **Keep fragments small** — big shared files create tight coupling
+5. **Overlay-specific overrides are fine** — an overlay's own patch always wins; diverging from a shared baseline is expected and supported
 
 ## See Also
 
 - [Creating Overlays](creating-overlays.md)
-- [Overlay Metadata](overlay-metadata-archive.md)
-- [Doctor Command](../README.md#doctor-command)
+- `overlays/.shared/README.md` — shared fragment catalogue with usage details
+- CONTRIBUTING.md — overlay authoring guide

package/docs/overlays.md

@@ -69,12 +69,13 @@ Jupyter notebook server for interactive computing and data science
 
 Material for MkDocs - professional documentation generator
 
-| Property     | Value                               |
-| ------------ | ----------------------------------- |
-| **Category** | language                            |
-| **Requires** | `python`                            |
-| **Tags**     | `documentation`, `mkdocs`, `python` |
-| **Ports**    | 8000                                |
+| Property      | Value                               |
+| ------------- | ----------------------------------- |
+| **Category**  | language                            |
+| **Requires**  | `python`                            |
+| **Conflicts** | `mkdocs2`                           |
+| **Tags**      | `documentation`, `mkdocs`, `python` |
+| **Ports**     | 8000                                |
 
 ### Node.js (`nodejs`)
 
@@ -452,6 +453,16 @@ Specify CLI for Spec-Driven Development with any AI coding agent
 | **Suggests** | `python`, `codex`                                        |
 | **Tags**     | `dev`, `ai`, `sdd`, `spec-driven`, `specify`, `spec-kit` |
 
+### Pandoc PDF (`pandoc`)
+
+Pandoc with XeLaTeX, Mermaid diagrams, and quality fonts for Markdown-to-PDF export
+
+| Property     | Value                                                          |
+| ------------ | -------------------------------------------------------------- |
+| **Category** | dev                                                            |
+| **Suggests** | `nodejs`                                                       |
+| **Tags**     | `dev`, `pandoc`, `pdf`, `latex`, `markdown`, `docs`, `mermaid` |
+
 ### Amp (`amp`)
 
 Sourcegraph Amp CLI for AI-powered code generation and assistance
@@ -503,6 +514,26 @@ Conventional commits validation for automated releases
 | **Suggests** | `pre-commit`                                |
 | **Tags**     | `dev`, `git`, `commits`, `semantic-release` |
 
+### CUDA (NVIDIA GPU) (`cuda`)
+
+NVIDIA CUDA libraries and GPU passthrough for containerized ML/inference workloads
+
+| Property      | Value                                             |
+| ------------- | ------------------------------------------------- |
+| **Category**  | dev                                               |
+| **Conflicts** | `rocm`                                            |
+| **Tags**      | `dev`, `gpu`, `cuda`, `nvidia`, `ml`, `inference` |
+
+### Dev Container CLI (`devcontainer-cli`)
+
+Official devcontainer CLI for building and testing devcontainer configurations
+
+| Property     | Value                                   |
+| ------------ | --------------------------------------- |
+| **Category** | dev                                     |
+| **Suggests** | `docker-sock`, `docker-in-docker`       |
+| **Tags**     | `dev`, `devcontainer`, `cli`, `testing` |
+
 ### direnv (`direnv`)
 
 Per-directory environment variable management
@@ -592,6 +623,18 @@ Email testing tool with web UI and SMTP server
 | **Tags**     | `dev`, `email`, `smtp`, `testing` |
 | **Ports**    | [object Object], [object Object]  |
 
+### MkDocs 2 (`mkdocs2`)
+
+MkDocs 2.0 pre-release (encode/mkdocs) — smart, simple website design tool
+
+| Property      | Value                                      |
+| ------------- | ------------------------------------------ |
+| **Category**  | dev                                        |
+| **Requires**  | `python`                                   |
+| **Conflicts** | `mkdocs`                                   |
+| **Tags**      | `dev`, `documentation`, `mkdocs`, `python` |
+| **Ports**     | 8000                                       |
+
 ### Modern CLI Tools (`modern-cli-tools`)
 
 jq, yq, ripgrep, fd, bat - Essential modern command-line tools
@@ -652,6 +695,16 @@ Automated code quality gates with pre-commit hooks
 | **Suggests** | `commitlint`                     |
 | **Tags**     | `dev`, `git`, `quality`, `hooks` |
 
+### ROCm (AMD GPU) (`rocm`)
+
+AMD ROCm libraries and GPU passthrough for containerized ML/inference workloads
+
+| Property      | Value                                          |
+| ------------- | ---------------------------------------------- |
+| **Category**  | dev                                            |
+| **Conflicts** | `cuda`                                         |
+| **Tags**      | `dev`, `gpu`, `rocm`, `amd`, `ml`, `inference` |
+
 ### Tilt (`tilt`)
 
 Live update and orchestration for Kubernetes development

package/docs/quick-reference.md

@@ -162,6 +162,105 @@ npm run init -- \
   --cloud-tools aws-cli,azure-cli,kubectl-helm
 ```
 
+## Doctor Command
+
+The `doctor` command validates the current environment and devcontainer configuration.
+
+### Basic Diagnostics
+
+```bash
+# Run diagnostics against the default .devcontainer/
+container-superposition doctor
+
+# Specify a custom path
+container-superposition doctor --output ./my-project/.devcontainer
+
+# Point to a manifest file directly (outputPath is derived from the manifest)
+container-superposition doctor --from-manifest ./superposition.json
+
+# Load the output path from the repository project file (superposition.yml)
+container-superposition doctor --from-project
+
+# Run discovery relative to a different repository root
+container-superposition doctor --project-root /path/to/repo
+
+# Machine-readable JSON output
+container-superposition doctor --json
+```
+
+### Auto-Repair with `--fix`
+
+The `--fix` flag runs the full diagnosis and then attempts to automatically repair
+any fixable issues:
+
+```bash
+# Interactive auto-repair (text output)
+container-superposition doctor --fix
+
+# Machine-readable repair output (for CI/scripting)
+container-superposition doctor --fix --json
+```
+
+**Fix run output vocabulary:**
+
+| Outcome                  | Meaning                                              |
+| ------------------------ | ---------------------------------------------------- |
+| `fixed`                  | Tool changed the environment; re-check now passes    |
+| `already compliant`      | No change needed — check already passed              |
+| `skipped`                | Not attempted (prerequisite step failed)             |
+| `requires manual action` | Automation unsafe/unavailable; manual steps provided |
+
+**Fixable issue classes:**
+
+| Issue                                        | Auto-fix condition                                         |
+| -------------------------------------------- | ---------------------------------------------------------- |
+| Stale / legacy `superposition.json` manifest | Always — migrate to current schema                         |
+| Missing or corrupt `devcontainer.json`       | When a valid manifest is present — regenerate              |
+| Unsupported Node.js runtime                  | Only when `nvm`, `fnm`, or `volta` is installed            |
+| Docker daemon not accessible                 | Manual only — platform-specific restart instructions shown |
+
+**Remediation ordering:** Manifest migration always runs before devcontainer regeneration.
+If migration fails, regeneration is skipped and marked as `skipped`.
+
+**Safety:** All file mutations use atomic write (write to `.tmp`, then rename).
+A timestamped backup is created before any manifest is modified.
+
+**Exit codes:**
+
+- `0` — all findings resolved (success or already-compliant)
+- `0` — some findings require manual action (`repaired-with-warnings`)
+- `1` — unresolved failures remain after fix run
+
+### JSON Fix Run Structure
+
+```json
+{
+  "outputPath": "./.devcontainer",
+  "requestedJson": true,
+  "initialFindings": [...],
+  "executions": [
+    {
+      "findingId": "manifest-version",
+      "remediationKey": "manifest-migration",
+      "attempted": true,
+      "outcome": "fixed",
+      "reason": "Manifest migrated to current schema version",
+      "changedFiles": [".devcontainer/superposition.json"],
+      "backupPath": ".devcontainer/superposition.json.backup-2026-03-19-..."
+    }
+  ],
+  "finalFindings": [...],
+  "summary": {
+    "fixed": 1,
+    "alreadyCompliant": 3,
+    "skipped": 0,
+    "requiresManualAction": 0,
+    "total": 4
+  },
+  "exitDisposition": "success"
+}
+```
+
 ## Output Structure
 
 ### Minimal (plain + language)

package/docs/specs/002-superposition-config-file/plan.md

@@ -17,7 +17,12 @@ The design extends the existing answer-merging flow instead of creating a second
 generation pipeline, introduces an explicit `--from-project` mode, allows
 implicit project-file use for `init --no-interactive` and default `regen` when
 no conflicting source or selection flags are supplied, and keeps explicit
-manifest-based regeneration as a separate persisted-input mode.
+manifest-based regeneration as a separate persisted-input mode. The same schema
+must also be writable from `adopt --project-file` so migration from an existing
+`.devcontainer/` can produce a repository-root project config without inventing
+a parallel declaration format. Persisted-input workflows must also support an
+explicit repository-root override so users can run `init` or `regen` against a
+different repository without first changing their shell working directory.
 
 ## Technical Context
 

package/docs/specs/002-superposition-config-file/spec.md

@@ -29,6 +29,8 @@ A project maintainer defines the desired development environment in a single rep
 
 1. **Given** a repository with a valid project config file in its root that defines stack, overlay selections, output location, and supported customization settings, **When** a maintainer runs the generation flow from that repository root, **Then** the tool uses those values as the starting configuration for generation.
 2. **Given** a repository with a committed project config file, **When** a teammate clones the repository and runs the same generation flow from a fresh checkout, **Then** they receive the same effective project setup without needing the original author’s shell history or copied command examples.
+3. **Given** a repository with an existing hand-crafted `.devcontainer/`, **When** a maintainer runs `adopt --project-file`, **Then** the tool writes a repository-root project config that captures the inferred stack, overlay selections, output path, and supported customization inputs from the adopted setup.
+4. **Given** a maintainer is working outside the target repository, **When** they run `init --from-project --project-root <path>` or `regen --project-root <path>`, **Then** the tool resolves the project file and relative output paths from that selected repository root.
 
 ---
 
@@ -72,6 +74,8 @@ A contributor receives clear guidance when the project config file is invalid, i
 - How does the system handle supported customizations such as environment settings, custom container definitions, or additional generated features? Those values are treated as first-class generation inputs and must round-trip through the project config file without being dropped.
 - How does the system handle unsupported overlay IDs, invalid categories, or conflicting selections in the project config file? It fails validation before generation and explains the invalid entries.
 - How does the system handle both `.superposition.yml` and `superposition.yml` in one repository? It treats this as an error to avoid ambiguity.
+- How does the system handle `adopt --project-file` when a repository already contains a supported project config file? It reuses that file path, and it must still stop on dual-file ambiguity so the source of truth stays deterministic.
+- How does the system handle project-file or manifest discovery from outside the target repository? An explicit project-root option may redirect persisted-input discovery and relative output resolution to that repository root.
 
 ## Requirements _(mandatory)_
 
@@ -96,6 +100,8 @@ A contributor receives clear guidance when the project config file is invalid, i
 - **FR-017**: The system MUST allow `init --no-interactive` and `regen` to use the repository project file implicitly when a valid project config file exists and no other persisted-input source flag or clean-generation selection flags are supplied.
 - **FR-018**: The system MUST reject conflicting persisted-input source combinations before generation, including `--from-project` with `--from-manifest` and either source-selection mode combined with clean-generation selection flags such as stack, overlay, or preset selection.
 - **FR-019**: The system MUST document how teams create, commit, validate, and use the project config file in local development, regeneration, and automation workflows, including how parity with clean generation applies to supported customization inputs and how source-selection conflicts are resolved.
+- **FR-020**: The system MUST allow `adopt --project-file` to write a repository-root project config that represents the inferred adopted setup using the same supported declaration surface as other project-config workflows.
+- **FR-021**: The system MUST allow `init` and `regen` to resolve project-file and manifest discovery from an explicitly selected repository root so users can run persisted-input workflows without changing their shell working directory first.
 
 ### Key Entities _(include if feature involves data)_
 

package/docs/specs/002-superposition-config-file/tasks.md

@@ -60,6 +60,8 @@
 - [x] T016 [US1] Preserve supported customization inputs through generation and summary rendering in `scripts/init.ts`
 - [x] T017 [US1] Ensure project-config driven answers produce the same composed output as equivalent clean-generation input in `tool/questionnaire/composer.ts`
 - [x] T018 [US1] Keep generated run summaries accurate for project-config sourced generation in `tool/utils/summary.ts`
+- [x] T018a [US1] Let `adopt --project-file` write a repository-root project config from inferred overlay selections and supported customizations in `tool/commands/adopt.ts` and `tool/schema/project-config.ts`
+- [x] T018b [US1] Let `init` and `regen` target a different repository root for project-file and manifest discovery via `--project-root <path>` in `scripts/init.ts` and `tool/__tests__/commands.test.ts`
 
 **Checkpoint**: User Story 1 should now be fully functional and testable on its own