feat: add docs

.gitignore

@@ -1,5 +1,6 @@
 # Binaries
 bin/
+gendocs
 *.exe
 *.exe~
 *.dll

cmd/daco/internal/app.go

@@ -19,6 +19,7 @@ import (
 	"github.com/dacolabs/cli/internal/translate/pyspark"
 	"github.com/dacolabs/cli/internal/translate/python"
 	"github.com/dacolabs/cli/internal/translate/scala"
+	"github.com/dacolabs/cli/internal/translate/sparkscala"
 	"github.com/dacolabs/cli/internal/translate/sparksql"
 )
 
@@ -32,7 +33,7 @@ func registerTranslators() translate.Register {
 	translators["python"] = &python.Translator{}
 	translators["databricks-sql"] = &databrickssql.Translator{}
 	translators["scala"] = &scala.Translator{}
-	translators["spark-scala"] = &pyspark.Translator{}
+	translators["spark-scala"] = &sparkscala.Translator{}
 	translators["databricks-scala"] = &databricksscala.Translator{}
 	translators["protobuf"] = &protobuf.Translator{}
 	translators["spark-sql"] = &sparksql.Translator{}

cmd/gendocs/main.go

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Daco Labs
+
+// Command gendocs generates LLM-friendly markdown documentation for the daco CLI.
+//
+// Usage:
+//
+//	go run ./cmd/gendocs [output-dir]
+//
+// Default output directory is ./docs/cli.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/dacolabs/cli/internal/commands"
+	"github.com/dacolabs/cli/internal/translate"
+	"github.com/dacolabs/cli/internal/translate/avro"
+	"github.com/dacolabs/cli/internal/translate/databrickspyspark"
+	"github.com/dacolabs/cli/internal/translate/databricksscala"
+	"github.com/dacolabs/cli/internal/translate/databrickssql"
+	"github.com/dacolabs/cli/internal/translate/gotypes"
+	"github.com/dacolabs/cli/internal/translate/protobuf"
+	"github.com/dacolabs/cli/internal/translate/pydantic"
+	"github.com/dacolabs/cli/internal/translate/pyspark"
+	"github.com/dacolabs/cli/internal/translate/python"
+	"github.com/dacolabs/cli/internal/translate/scala"
+	"github.com/dacolabs/cli/internal/translate/sparkscala"
+	"github.com/dacolabs/cli/internal/translate/sparksql"
+	"github.com/spf13/cobra/doc"
+)
+
+func main() {
+	dir := "./docs/cli"
+	if len(os.Args) > 1 {
+		dir = os.Args[1]
+	}
+
+	translators := make(translate.Register)
+	translators["pyspark"] = &pyspark.Translator{}
+	translators["gotypes"] = &gotypes.Translator{}
+	translators["avro"] = &avro.Translator{}
+	translators["databricks-pyspark"] = &databrickspyspark.Translator{}
+	translators["pydantic"] = &pydantic.Translator{}
+	translators["python"] = &python.Translator{}
+	translators["databricks-sql"] = &databrickssql.Translator{}
+	translators["scala"] = &scala.Translator{}
+	translators["spark-scala"] = &sparkscala.Translator{}
+	translators["databricks-scala"] = &databricksscala.Translator{}
+	translators["protobuf"] = &protobuf.Translator{}
+	translators["spark-sql"] = &sparksql.Translator{}
+
+	rootCmd := commands.NewRootCmd(translators)
+	rootCmd.DisableAutoGenTag = true
+
+	if err := os.MkdirAll(dir, 0o750); err != nil {
+		fmt.Fprintf(os.Stderr, "error creating output dir: %v\n", err)
+		os.Exit(1)
+	}
+
+	if err := doc.GenMarkdownTree(rootCmd, dir); err != nil {
+		fmt.Fprintf(os.Stderr, "error generating docs: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Printf("Documentation generated in %s\n", dir)
+}

docs/cli/daco.md

@@ -0,0 +1,23 @@
+## daco
+
+Data product CLI tool
+
+### Synopsis
+
+daco is a CLI for defining, managing, and translating data product specifications
+using the OpenDPI standard. It supports managing ports (with JSON schemas),
+infrastructure connections, and translating schemas to formats such as PySpark,
+Avro, Protobuf, Go types, and more.
+
+### Options
+
+```
+  -h, --help   help for daco
+```
+
+### SEE ALSO
+
+* [daco connections](daco_connections.md)	 - Manage data product connections
+* [daco init](daco_init.md)	 - Initialize a new daco project
+* [daco ports](daco_ports.md)	 - Manage data product ports
+

docs/cli/daco_connections.md

@@ -0,0 +1,24 @@
+## daco connections
+
+Manage data product connections
+
+### Synopsis
+
+Manage infrastructure connections defined in the OpenDPI spec. Connections
+describe how to reach external systems (Kafka, PostgreSQL, S3, HTTP, etc.)
+and are referenced by ports. Use subcommands to add, list, describe, or remove connections.
+
+### Options
+
+```
+  -h, --help   help for connections
+```
+
+### SEE ALSO
+
+* [daco](daco.md)	 - Data product CLI tool
+* [daco connections add](daco_connections_add.md)	 - Add a new connection to the OpenDPI spec
+* [daco connections describe](daco_connections_describe.md)	 - Show detailed information about a connection
+* [daco connections list](daco_connections_list.md)	 - List all connections in the OpenDPI spec
+* [daco connections remove](daco_connections_remove.md)	 - Remove a connection from the OpenDPI spec
+

docs/cli/daco_connections_add.md

@@ -0,0 +1,37 @@
+## daco connections add
+
+Add a new connection to the OpenDPI spec
+
+### Synopsis
+
+Add a new infrastructure connection to the OpenDPI spec.
+
+```
+daco connections add [flags]
+```
+
+### Examples
+
+```
+  # Interactive mode
+  daco connections add
+
+  # Non-interactive
+  daco connections add -n kafka_prod -p kafka --host broker:9092 --non-interactive
+```
+
+### Options
+
+```
+  -d, --description string   Description
+  -h, --help                 help for add
+      --host string          Host/endpoint
+  -n, --name string          Connection name
+      --non-interactive      Run without prompts
+  -p, --protocol string      Protocol (kafka, postgresql, mysql, s3, http, etc.)
+```
+
+### SEE ALSO
+
+* [daco connections](daco_connections.md)	 - Manage data product connections
+

docs/cli/daco_connections_describe.md

@@ -0,0 +1,39 @@
+## daco connections describe
+
+Show detailed information about a connection
+
+### Synopsis
+
+Display complete connection details including which ports use it. If no connection name is provided, an interactive selection prompt is shown.
+
+```
+daco connections describe [CONNECTION_NAME] [flags]
+```
+
+### Examples
+
+```
+  # Interactive selection
+  daco connections describe
+
+  # Show connection details
+  daco connections describe kafka_prod
+
+  # Show as JSON
+  daco connections describe kafka_prod -o json
+
+  # Show as YAML
+  daco connections describe kafka_prod -o yaml
+```
+
+### Options
+
+```
+  -h, --help            help for describe
+  -o, --output string   Output format (text, json, yaml) (default "text")
+```
+
+### SEE ALSO
+
+* [daco connections](daco_connections.md)	 - Manage data product connections
+

docs/cli/daco_connections_list.md

@@ -0,0 +1,36 @@
+## daco connections list
+
+List all connections in the OpenDPI spec
+
+### Synopsis
+
+List all connections defined in the OpenDPI spec with their protocols and hosts.
+
+```
+daco connections list [flags]
+```
+
+### Examples
+
+```
+  # List connections in table format
+  daco connections list
+
+  # List connections as JSON
+  daco connections list -o json
+
+  # List connections as YAML
+  daco connections list -o yaml
+```
+
+### Options
+
+```
+  -h, --help            help for list
+  -o, --output string   Output format (table, json, yaml) (default "table")
+```
+
+### SEE ALSO
+
+* [daco connections](daco_connections.md)	 - Manage data product connections
+

docs/cli/daco_connections_remove.md

@@ -0,0 +1,36 @@
+## daco connections remove
+
+Remove a connection from the OpenDPI spec
+
+### Synopsis
+
+Remove a connection from the OpenDPI spec. Cannot remove connections that are in use by ports. If no connection name is provided, an interactive selection prompt is shown.
+
+```
+daco connections remove [CONNECTION_NAME] [flags]
+```
+
+### Examples
+
+```
+  # Interactive selection
+  daco connections remove
+
+  # Remove with confirmation
+  daco connections remove unused_conn
+
+  # Remove without confirmation
+  daco connections remove unused_conn --force
+```
+
+### Options
+
+```
+  -f, --force   Skip confirmation prompt
+  -h, --help    help for remove
+```
+
+### SEE ALSO
+
+* [daco connections](daco_connections.md)	 - Manage data product connections
+

docs/cli/daco_init.md

@@ -0,0 +1,41 @@
+## daco init
+
+Initialize a new daco project
+
+### Synopsis
+
+Initialize a new daco project with a daco.yaml configuration file.
+Can create a new spec, use an existing one, or extend a parent config.
+
+```
+daco init [flags]
+```
+
+### Examples
+
+```
+  # Interactive mode
+  daco init
+
+  # Non-interactive
+  daco init --name "my-product" --non-interactive
+  daco init --extends ../daco.yaml --non-interactive
+```
+
+### Options
+
+```
+  -e, --extends string               Path to parent daco.yaml
+  -f, --format string                Spec format (yaml or json) (default "yaml")
+  -h, --help                         help for init
+  -n, --name string                  Project name
+      --non-interactive              Run without prompts (requires --name or --extends)
+  -p, --path string                  Path to spec folder (default "./spec")
+  -s, --schema-organization string   Schema organization (modular, components, or inline) (default "modular")
+  -v, --version string               Initial spec version (default "1.0.0")
+```
+
+### SEE ALSO
+
+* [daco](daco.md)	 - Data product CLI tool
+

docs/cli/daco_ports.md

@@ -0,0 +1,25 @@
+## daco ports
+
+Manage data product ports
+
+### Synopsis
+
+Manage data product ports defined in the OpenDPI spec. Ports represent
+data interfaces (input or output) with associated JSON schemas and connections.
+Use subcommands to add, list, describe, remove, or translate port schemas.
+
+### Options
+
+```
+  -h, --help   help for ports
+```
+
+### SEE ALSO
+
+* [daco](daco.md)	 - Data product CLI tool
+* [daco ports add](daco_ports_add.md)	 - Add a new port to the OpenDPI spec
+* [daco ports describe](daco_ports_describe.md)	 - Show detailed information about a port
+* [daco ports list](daco_ports_list.md)	 - List all ports in the OpenDPI spec
+* [daco ports remove](daco_ports_remove.md)	 - Remove a port from the OpenDPI spec
+* [daco ports translate](daco_ports_translate.md)	 - Translate a port schema to a target format
+