From b4203a4a09078f76f6adcbf72efb693a39cb13e5 Mon Sep 17 00:00:00 2001 From: Developer Date: Sun, 14 Jun 2026 10:32:13 +0000 Subject: [PATCH] chore: update project maps for tool container home directory artifacts --- .pi-map.index.md | 2 +- .pi-map.md | 4 ++-- docs/.pi-map.index.md | 2 +- docs/.pi-map.md | 4 ++-- docs/superpowers/.pi-map.index.md | 2 +- docs/superpowers/.pi-map.md | 4 ++-- docs/superpowers/plans/.pi-map.index.md | 3 ++- docs/superpowers/plans/.pi-map.md | 7 ++++--- docs/superpowers/specs/.pi-map.index.md | 3 ++- docs/superpowers/specs/.pi-map.md | 7 ++++--- openspec/.pi-map.index.md | 2 +- openspec/.pi-map.md | 4 ++-- openspec/designs/.pi-map.index.md | 3 ++- openspec/designs/.pi-map.md | 7 ++++--- openspec/tasks/.pi-map.index.md | 2 +- openspec/tasks/.pi-map.md | 8 ++++---- 16 files changed, 35 insertions(+), 29 deletions(-) diff --git a/.pi-map.index.md b/.pi-map.index.md index c01c767..b8ab15b 100644 --- a/.pi-map.index.md +++ b/.pi-map.index.md @@ -16,7 +16,7 @@ dir: . Trust boundary: index routes, map orients, source decides. ## role -Infrastructure and deployment configuration for a self-hosted project management platform with git repository management and OAuth2 authentication. +Infrastructure and deployment configuration for a self-hosted project management platform with OAuth2 authentication, providing Docker orchestration, environment setup, and development tooling. ## parent - ## children diff --git a/.pi-map.md b/.pi-map.md index d493958..4b7a2b2 100644 --- a/.pi-map.md +++ b/.pi-map.md @@ -18,7 +18,7 @@ index: ./.pi-map.index.md Trust boundary: index routes, map orients, source decides. ## role -Infrastructure and deployment configuration for a self-hosted project management platform with git repository management and OAuth2 authentication. +Infrastructure and deployment configuration for a self-hosted project management platform with OAuth2 authentication, providing Docker orchestration, environment setup, and development tooling. ## files - .env.example | Provides a template of environment variables for configuring a Headquarter application with PostgreSQL, Redis, Authentik SSO, and Docker/Traefik deployment - .gitignore | Specifies files and directories for Git to ignore across a multi-language project with Python, Node, and custom tooling | dep: Git @@ -31,7 +31,7 @@ Infrastructure and deployment configuration for a self-hosted project management - progress.md | Tracks completed and remaining tasks for a backend-frontend code refactoring project organized in 7 phases - swap-pane | Empty file with no functionality ## arch -Containerized microservices architecture using Docker Compose with PostgreSQL/Redis backend, Traefik reverse proxy for TLS termination, and environment-driven configuration management. +Containerized microservices architecture using Docker Compose with PostgreSQL/Redis backend services, Traefik reverse proxy with TLS termination, environment-based configuration, and Makefile-driven development lifecycle management. ## tags docker, redis, git, application, postgresql, compose, traefik, project ## symbols diff --git a/docs/.pi-map.index.md b/docs/.pi-map.index.md index 2ca5a0f..ccf5ee4 100644 --- a/docs/.pi-map.index.md +++ b/docs/.pi-map.index.md @@ -2,7 +2,7 @@ dir: docs ## role -Provides user-facing documentation and knowledge base for the Headquarter platform. +Central documentation hub and knowledge base for the Headquarter platform. ## parent index: ./.pi-map.index.md map: ./.pi-map.md diff --git a/docs/.pi-map.md b/docs/.pi-map.md index f9ec4aa..d6fe630 100644 --- a/docs/.pi-map.md +++ b/docs/.pi-map.md @@ -4,11 +4,11 @@ dir: docs index: docs/.pi-map.index.md ## role -Provides user-facing documentation and knowledge base for the Headquarter platform. +Central documentation hub and knowledge base for the Headquarter platform. ## files - README.md | Serves as the main index and navigation hub for the Headquarter platform documentation, organizing links to feature guides, API docs, architecture, deployment, and development resources. ## arch -Static documentation site using markdown files organized hierarchically with a central README index. +Static documentation organization using hierarchical markdown files with cross-referenced navigation structure. ## tags readme, serves, main, index, navigation, hub, headquarter, platform ## symbols diff --git a/docs/superpowers/.pi-map.index.md b/docs/superpowers/.pi-map.index.md index eeb0793..3cf2f8e 100644 --- a/docs/superpowers/.pi-map.index.md +++ b/docs/superpowers/.pi-map.index.md @@ -2,7 +2,7 @@ dir: docs/superpowers ## role -Documentation directory for specialized or advanced capabilities/features of the project. +Documentation for advanced or specialized features and capabilities of the project. ## parent index: docs/.pi-map.index.md map: docs/.pi-map.md diff --git a/docs/superpowers/.pi-map.md b/docs/superpowers/.pi-map.md index cd2d16b..af9d699 100644 --- a/docs/superpowers/.pi-map.md +++ b/docs/superpowers/.pi-map.md @@ -4,10 +4,10 @@ dir: docs/superpowers index: docs/superpowers/.pi-map.index.md ## role -Documentation directory for specialized or advanced capabilities/features of the project. +Documentation for advanced or specialized features and capabilities of the project. ## files ## arch -Static documentation storage with no executable code architecture; likely contains markdown or text files describing enhanced functionality. +Flat documentation structure with topic-based markdown files describing extended functionality beyond core features. ## tags - ## symbols diff --git a/docs/superpowers/plans/.pi-map.index.md b/docs/superpowers/plans/.pi-map.index.md index d849815..241094f 100644 --- a/docs/superpowers/plans/.pi-map.index.md +++ b/docs/superpowers/plans/.pi-map.index.md @@ -2,7 +2,7 @@ dir: docs/superpowers/plans ## role -Contains implementation planning documents for core infrastructure, authentication, database modeling, and UI feature development. +Contains dated implementation planning documents that specify step-by-step technical approaches for major infrastructure, authentication, database, and UI feature development. ## parent index: docs/superpowers/.pi-map.index.md map: docs/superpowers/.pi-map.md @@ -13,6 +13,7 @@ map: docs/superpowers/.pi-map.md - 2026-05-17-auth-oauth.md - 2026-05-17-database-models.md - 2026-05-24-session-branch-selection.md +- tool-container-home-directory.md ## links index: docs/superpowers/plans/.pi-map.index.md map: docs/superpowers/plans/.pi-map.md diff --git a/docs/superpowers/plans/.pi-map.md b/docs/superpowers/plans/.pi-map.md index e4fd3ce..f374762 100644 --- a/docs/superpowers/plans/.pi-map.md +++ b/docs/superpowers/plans/.pi-map.md @@ -4,16 +4,17 @@ dir: docs/superpowers/plans index: docs/superpowers/plans/.pi-map.index.md ## role -Contains implementation planning documents for core infrastructure, authentication, database modeling, and UI feature development. +Contains dated implementation planning documents that specify step-by-step technical approaches for major infrastructure, authentication, database, and UI feature development. ## files - 2024-05-16-docker-infrastructure.md | Defines a step-by-step implementation plan for setting up a complete Docker-based development infrastructure with multi-service orchestration including PostgreSQL, Redis, Traefik, Authentik, FastAPI backend, and React frontend. | dep: Docker, Docker Compose, Make, Python 3.11, Node.js 20, PostgreSQL, Redis, Traefik, Authentik, FastAPI, React, Vite, nginx, alembic, uvicorn, SQLAlchemy, pydantic, structlog - 2026-05-17-auth-oauth.md | Implementation plan for adding Authentik-backed OIDC authentication with JWT access tokens and DB-backed refresh tokens to a FastAPI application | dep: FastAPI, SQLAlchemy, Alembic, python-jose, httpx, pytest, Authentik, PostgreSQL - 2026-05-17-database-models.md | Define an implementation plan for building SQLAlchemy 2.0 async database models, Alembic migrations, and seed data for a FastAPI backend. | dep: SQLAlchemy 2.x, asyncpg, Alembic, pytest, pytest-asyncio, Pydantic Settings, PostgreSQL, FastAPI - 2026-05-24-session-branch-selection.md | Implementation plan for replacing free-text branch input with a dropdown of available branches and adding "Create new branch" functionality in a session creation form | dep: React, TypeScript, FastAPI, Python, Git subprocess, Pydantic, API client +- tool-container-home-directory.md | Implementation plan to make `/home/user` the configurable default home directory for tool containers while preserving repository name in mount targets, migrating legacy tool types, and maintaining `/workspace` backward compatibility symlink. | dep: Alembic, Docker, Compose, manifest compiler, instance service, config profile resolver, permission fixer, base dockerfile, pytest ## arch -Markdown-based technical specification documents using date-prefixed naming convention, each detailing phased implementation steps for specific system capabilities with technology stack integration points. +Document-driven planning architecture using chronological Markdown specifications with precise technical scope, dependencies, and migration strategies for incremental system evolution. ## tags -05, fastapi, 2026, implementation, plan, docker, postgresql, authentik +05, fastapi, 2026, implementation, plan, docker, alembic, postgresql ## symbols - ## workflows diff --git a/docs/superpowers/specs/.pi-map.index.md b/docs/superpowers/specs/.pi-map.index.md index 7667df9..bb460e5 100644 --- a/docs/superpowers/specs/.pi-map.index.md +++ b/docs/superpowers/specs/.pi-map.index.md @@ -2,7 +2,7 @@ dir: docs/superpowers/specs ## role -Contains design specification documents for planned system features, serving as architectural decision records for authentication and session management capabilities. +Contains design specifications and test plans for upcoming features ("superpowers") being planned for the project. ## parent index: docs/superpowers/.pi-map.index.md map: docs/superpowers/.pi-map.md @@ -11,6 +11,7 @@ map: docs/superpowers/.pi-map.md ## files - 2026-05-17-auth-oauth-design.md - 2026-05-24-session-branch-selection-design.md +- tool-container-home-directory-test-plan.md ## links index: docs/superpowers/specs/.pi-map.index.md map: docs/superpowers/specs/.pi-map.md diff --git a/docs/superpowers/specs/.pi-map.md b/docs/superpowers/specs/.pi-map.md index 3427747..aec4226 100644 --- a/docs/superpowers/specs/.pi-map.md +++ b/docs/superpowers/specs/.pi-map.md @@ -4,14 +4,15 @@ dir: docs/superpowers/specs index: docs/superpowers/specs/.pi-map.index.md ## role -Contains design specification documents for planned system features, serving as architectural decision records for authentication and session management capabilities. +Contains design specifications and test plans for upcoming features ("superpowers") being planned for the project. ## files - 2026-05-17-auth-oauth-design.md | Design document for implementing OAuth2/OIDC authentication with Authentik, internal JWT access tokens, and database-backed refresh token rotation. | dep: Authentik, JWKS, JWT, database/PostgreSQL, cookies, pytest, mypy, ruff - 2026-05-24-session-branch-selection-design.md | Design document for replacing free-text branch input with a dropdown of available branches and adding the ability to create a new local branch at clone time in a session creation UI. | dep: React/TypeScript frontend, Python/FastAPI backend, Git, API client, ToolInstance database model +- tool-container-home-directory-test-plan.md | Test plan and QA checklist for validating configurable home directory behavior in tool containers, covering manifest compilation, path expansion, database migrations, and mount target resolution. | dep: pytest, alembic, docker, compose, manifest compiler, instance service, ToolType, config profiles, git mounts ## arch -Markdown-based technical design documentation following a chronological naming convention (YYYY-MM-DD-feature-name-design.md) with no executable code, using a lightweight specification format for capturing requirements, decisions, and implementation plans before development. +Document-driven architecture using dated Markdown design documents for feature specifications, plus standalone test plans for QA validation of complex features. ## tags -design, 2026, 05, branch, session, document, authentik, jwt +design, 2026, 05, branch, database, session, test, plan ## symbols - ## workflows diff --git a/openspec/.pi-map.index.md b/openspec/.pi-map.index.md index 8802de7..02555ee 100644 --- a/openspec/.pi-map.index.md +++ b/openspec/.pi-map.index.md @@ -2,7 +2,7 @@ dir: openspec ## role -Defines the OpenSpec methodology and configuration for managing living documentation, requirements, and task tracking within a Docker-based coding agent platform. +Defines and configures the OpenSpec methodology for structured living documentation of requirements, specifications, and task tracking within a Docker-based coding agent management platform. ## parent index: ./.pi-map.index.md map: ./.pi-map.md diff --git a/openspec/.pi-map.md b/openspec/.pi-map.md index 34f1dd9..2ea06d3 100644 --- a/openspec/.pi-map.md +++ b/openspec/.pi-map.md @@ -4,12 +4,12 @@ dir: openspec index: openspec/.pi-map.index.md ## role -Defines the OpenSpec methodology and configuration for managing living documentation, requirements, and task tracking within a Docker-based coding agent platform. +Defines and configures the OpenSpec methodology for structured living documentation of requirements, specifications, and task tracking within a Docker-based coding agent management platform. ## files - README.md | Documents the OpenSpec methodology for managing software requirements, specifications, and task tracking as living documentation within a project repository. | dep: OpenSpec CLI (@fission-ai/openspec), Docker, SQLAlchemy, Alembic, Authentik, React, TypeScript, Tailwind, Traefik, Jinja2, xterm.js, pytest, mypy, ruff, npm - config.yaml | Configuration file defining project metadata, technology stack, and software development discipline rules for a Docker-based coding agent management platform | dep: FastAPI, React, Vite, PostgreSQL, SQLAlchemy, Redis, Alembic, pytest, Docker Compose, Traefik, Authentik ## arch -Documentation-as-code pattern with YAML-driven configuration, embedding specifications directly in the repository rather than external tools, supporting automated agent workflows. +Documentation-as-code pattern with YAML-driven configuration separating project metadata, technology stack definitions, and software development discipline rules from implementation code. ## tags software, project, docker, sqlalchemy, alembic, authentik, react, traefik ## symbols diff --git a/openspec/designs/.pi-map.index.md b/openspec/designs/.pi-map.index.md index a7d5b7f..5db0a0c 100644 --- a/openspec/designs/.pi-map.index.md +++ b/openspec/designs/.pi-map.index.md @@ -2,7 +2,7 @@ dir: openspec/designs ## role -Contains design documents specifying architectural decisions and feature specifications for the OpenSpec containerized development environment platform. +Design document repository for architectural specifications and technical planning of containerized development environment features. ## parent index: openspec/.pi-map.index.md map: openspec/.pi-map.md @@ -13,6 +13,7 @@ map: openspec/.pi-map.md - home-path-expansion.md - mount-specificity-ordering.md - terminal-responsiveness.md +- tool-container-home-directory.md - tool-definition-manifest.md ## links index: openspec/designs/.pi-map.index.md diff --git a/openspec/designs/.pi-map.md b/openspec/designs/.pi-map.md index 39d4102..044cbe8 100644 --- a/openspec/designs/.pi-map.md +++ b/openspec/designs/.pi-map.md @@ -4,17 +4,18 @@ dir: openspec/designs index: openspec/designs/.pi-map.index.md ## role -Contains design documents specifying architectural decisions and feature specifications for the OpenSpec containerized development environment platform. +Design document repository for architectural specifications and technical planning of containerized development environment features. ## files - config-profile-multi-repo-mounts.md | Design document for extending git mount configuration to support multiple source-to-target mappings per repository in a config profile system. | dep: JSONB, Python, TypeScript, React, os.path, glob expansion, config profile API, tool instances API - home-path-expansion.md | Design document for implementing `~` and `$HOME` expansion in container mount paths based on manifest user configuration | dep: config_profile_resolver.py, manifest_compiler.py, tool_instances.py, os - mount-specificity-ordering.md | Defines a design for sorting Docker volume mounts by target path depth to ensure more specific mounts take precedence, with duplicate detection warnings. | dep: docker.py, manifest_compiler.py, tool_instances.py, collections.Counter, logging - terminal-responsiveness.md | Design document for a high-performance web terminal rewrite using asyncio-native I/O, binary WebSocket frames, output batching, flow control, and WebGL rendering. | dep: asyncio, pty, os, time, collections.deque, xterm.js, xterm-addon-webgl, WebSocket, docker, JSON +- tool-container-home-directory.md | Proposes a design for standardizing tool container home directories to `/home/user` with configurable paths, meaningful repo mounts, and backward-compatible `/workspace` symlinks. | dep: ToolType model, manifest schema, Alembic, Docker/dockerfile, compose, config-profile mounts, git mounts, entrypoint permission fixer, home-path-expansion - tool-definition-manifest.md | Defines a system for creating, validating, and compiling tool definition manifests into Dockerfiles, Docker Compose files, and entrypoint scripts for containerized development environments. | dep: Docker, PostgreSQL, Python (json, hashlib, shlex, yaml, subprocess), JSON Schema, deb/nodesource package repositories ## arch -Markdown-based design document collection using iterative specification pattern; each document follows a structured RFC-style format with problem statement, design, and implementation considerations covering container orchestration, filesystem mounts, terminal I/O, and tool manifest compilation. +Markdown-based RFC-style design documents covering configuration systems, container filesystem layout, terminal I/O architecture, and Docker toolchain generation with emphasis on backward compatibility and incremental feature rollout. ## tags -py, docker, design, mount, path, mounts, document, config +home, py, docker, tool, design, path, mounts, mount ## symbols - ## workflows diff --git a/openspec/tasks/.pi-map.index.md b/openspec/tasks/.pi-map.index.md index 42bf66a..0011557 100644 --- a/openspec/tasks/.pi-map.index.md +++ b/openspec/tasks/.pi-map.index.md @@ -2,7 +2,7 @@ dir: openspec/tasks ## role -Contains technical specification documents tracking planned features and architectural improvements for the container development environment platform. +Technical specification and task tracking directory for planned engineering improvements across the project's container runtime, workspace management, and developer tooling systems. ## parent index: openspec/.pi-map.index.md map: openspec/.pi-map.md diff --git a/openspec/tasks/.pi-map.md b/openspec/tasks/.pi-map.md index 913fd3b..8accd6c 100644 --- a/openspec/tasks/.pi-map.md +++ b/openspec/tasks/.pi-map.md @@ -4,17 +4,17 @@ dir: openspec/tasks index: openspec/tasks/.pi-map.index.md ## role -Contains technical specification documents tracking planned features and architectural improvements for the container development environment platform. +Technical specification and task tracking directory for planned engineering improvements across the project's container runtime, workspace management, and developer tooling systems. ## files - config-profile-multi-repo-mounts.md | Technical specification for refactoring git mount configuration to support multiple repository mappings per mount instead of single source/target pairs | dep: git, docker compose, react/typescript, pytest, npm, fastapi -- home-path-expansion.md | Specification document for implementing ~ and $HOME expansion in container mount paths across backend services | dep: config_profile_resolver, manifest_compiler, tool_instances, pytest, npm +- home-path-expansion.md | Defines a technical implementation plan for adding configurable home/workspace directory support to tool containers in an API service. | dep: SQLAlchemy/Alembic, Docker, Docker Compose, Jinja2 templating, pytest, npm/frontend tooling - mount-specificity-ordering.md | Tracks completion status of a project task for implementing mount specificity ordering in Docker volume handling | dep: docker.py, pytest, tsc - terminal-responsiveness.md | A technical specification document outlining 7 pending tasks to improve web terminal performance through asyncio-native I/O, binary WebSocket frames, WebGL rendering, flow control, and comprehensive benchmarking. | dep: asyncio, WebSocket, xterm-addon-webgl, docker, pytest - tool-definition-manifest.md | A project task specification document defining a multi-PR system for implementing a Tool Definition Manifest System with backend manifest compilation, frontend workshop UI, and legacy migration support. | dep: SQLAlchemy, Alembic, Docker, Docker Compose, FastAPI/REST API, React/TypeScript frontend ## arch -Markdown-based task tracking system using specification-driven development with documents covering backend services (mount handling, path expansion), frontend systems (WebGL terminal rendering), and cross-cutting concerns (async I/O, manifest systems). +Markdown-based living documentation pattern using standalone specification files that each capture a discrete technical initiative with implementation plans, completion tracking, and cross-referencing between backend API changes, frontend UI work, and infrastructure migrations. ## tags -mount, specification, pytest, docker, manifest, multi, document, implementing +mount, docker, pytest, tool, manifest, technical, specification, support ## symbols - ## workflows