Constellation Portal

Constellation Portal is a Rust-based CLI that converts curated markdown collections (requirements, ADRs, audits, tasks) into a static, themeable knowledge portal. It follows the plan vision of shipping a single, extensible binary with configurable defaults and quick scaffolding for new documents.

Features

• constellate build turns a workspace directory into a distributable static site (implementation placeholder for now).
• constellate serve watches the workspace, rebuilds on changes, and serves the Material-themed portal with live reload (port configurable via --port and --no-watch to disable).
• The generated home page includes a Material-styled task digest that surfaces in-progress, next-up, and recently finished tasks; tweak the number of entries via .constellate.toml (cards.task_summary_limit).
• Sidebar navigation supports configurable collections per document type (status buckets with per-bucket limits) plus an optional "View all" drawer that reuses the search index for scoped browsing.
• constellate status enforces per-type workflows (todo/ready/in-progress/done, etc.), updates front matter, and logs transitions under a ## Changes section.
• constellate new scaffolds ADRs, tasks, or audits with sensible front matter, sequential IDs (based on configurable prefixes/widths), ID-prefixed slugified filenames (configurable globally or per document type), and a created: YYYY-MM-DD HH:MM:SS timestamp.
• constellate validate checks markdown syntax (frontmatter structure, YAML validity) and validates internal links, with options for syntax-only or links-only checks and path filtering for targeted validation.
• [document_types.list] can emit auto-generated list documents (an "all" view plus optional per-status partitions) and surface them as shortcuts at the top of the navigation sidebar.
• constellate init bootstraps a brand-new workspace by creating workspace/pages with a welcome doc, a minimal .constellate.toml, and a .gitignore that ignores workspace/dist.
• constellate theme list enumerates built-in layouts so teams can plan overrides, and constellate theme export copies the default templates into your workspace for customization.
• constellate dump-config writes the default .constellate.toml so teams can override folders, document types, and templates.

Requirements

• Rust 1.76+ with cargo.
• Optional: Nix for reproducible shells (nix-shell nix/shell.nix).

Nix Integration

• nix run github:onjin/constellate executes the packaged CLI directly from the flake, while nix shell github:onjin/constellate drops the binary into a subshell.
• nix develop github:onjin/constellate reuses nix/shell.nix so you can enter the development environment without cloning.
• flake.nix exposes packages.constellate, an overlay, and dev shells so other flakes can inputs.constellate and reference self.packages.${system}.constellate.
• NixOS systems can enable the CLI via imports = [ inputs.constellate.nixosModules.constellate ]; programs.constellate.enable = true;.
• Home Manager users can import inputs.constellate.homeManagerModules.constellate and toggle programs.constellate.enable = true to add the binary to home.packages.
• nix develop or nix flake check rely on the same shell definition used by nix-shell nix/shell.nix.

Shell Completions

• Run constellate completion --shell bash > constellate.bash to generate a Bash completion script (other shells supported via --shell).
• Source the generated script manually or drop it into your shell's completion directory.
• The NixOS/Home Manager modules set enableBashIntegration = true by default, which enables Bash completion when you toggle programs.constellate.enable = true.

Contributing

Development workflow, template guard rails, and documentation expectations now live in CONTRIBUTING.md. Refer to that guide for cargo commands, template export instructions, and the renderer migration plan before opening a PR.

Project Layout

• src/main.rs – clap-powered CLI entry point.
• Cargo.toml – crate metadata and dependencies (clap, color-eyre).
• nix/shell.nix – development environment definition.
• workspace/pages/ – default document tree (requirements, docs, support, tasks, ADRs, audits, initiatives) that tracks Constellate itself and serves as the sample input for constellate build.
• workspace/.constellate.toml – workspace-scoped configuration that maps document types to folders and points to the template overrides directory.
• workspace/templates/ – optional override directory for Minijinja templates and partials referenced by the theme configuration.

Next Steps

1. Extract the generator, status manager, and server utilities into dedicated modules with unit tests for markdown parsing, navigation rendering, and status transitions.
2. Expand configuration loading so teams can define additional document types, status workflows, and dashboard cards without touching the binary.
3. Implement theme discovery plus user asset overrides to complement the default Material skin. .constellate.toml also governs per-type status workflows and ID generation. Each [[document_types]] entry can define statuses = [...] plus id = { prefix = "REQ-", width = 3 } so constellate new always issues the next sequential identifier with consistent padding. Use the [portal] block to customize the site title/subtitle that appear in the header and hero (defaults to “Constellate Portal” / “Markdown → Material UI”).