Merge pull request #2159 from tisnik/lcore-2933-developer-doc

LCORE-2933: Developer doc

Author: tisnik

.github/workflows/openapi_spectral.yaml

@@ -26,17 +26,17 @@ jobs:
       - name: Install PDM
         # scripts/generate_openapi_schema.py asserts OpenAPI info.version matches `pdm show --version`.
         run: uv pip install pdm
-      - name: Verify docs/openapi.json matches generator
+      - name: Verify docs/devel_doc/openapi.json matches generator
         run: |
           set -euo pipefail
           uv run python scripts/generate_openapi_schema.py /tmp/openapi-generated.json
-          if ! diff -u docs/openapi.json /tmp/openapi-generated.json; then
-            echo "::error::docs/openapi.json is out of date. Regenerate with: uv run scripts/generate_openapi_schema.py docs/openapi.json"
+          if ! diff -u docs/devel_doc/openapi.json /tmp/openapi-generated.json; then
+            echo "::error::docs/devel_doc/openapi.json is out of date. Regenerate with: uv run scripts/generate_openapi_schema.py docs/devel_doc/openapi.json"
             exit 1
           fi
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: "22"
       - name: Spectral lint
-        run: npx --yes @stoplight/spectral-cli@6 lint docs/openapi.json --fail-severity error --display-only-failures
+        run: npx --yes @stoplight/spectral-cli@6 lint docs/devel_doc/openapi.json --fail-severity error --display-only-failures

docs/README.md

@@ -9,14 +9,10 @@ See the full documentation at [`../README.md`](../README.md) or browse sub-pages
 
 * [Basic info](#basic-info)
 * [User docs](#user-docs)
-* [Overview](#overview)
-* [Installation and configuration](#installation-and-configuration)
-* [Status of Lightspeed Core Stack versions](#status-of-lightspeed-core-stack-versions)
+* [Developer doc](#developer-doc)
+    * [API](#api)
+* [Maintenance](#maintenance)
 * [Migration guides](#migration-guides)
-* [Info for developers](#info-for-developers)
-* [API](#api)
-* [RAG and BYOK](#rag-and-byok)
-* [Other features](#other-features)
 * [Models](#models)
 * [Design documents](#design-documents)
     * [Agent skills](#agent-skills)
@@ -58,53 +54,47 @@ See the full documentation at [`../README.md`](../README.md) or browse sub-pages
 
 [User data collection](https://lightspeed-core.github.io/lightspeed-stack/user_doc/user_data_collection.html)
 
-## Overview
+## Developer doc
 
-[Architecture](https://lightspeed-core.github.io/lightspeed-stack/ARCHITECTURE.html)
+[Architecture](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/ARCHITECTURE.html)
 
-[Architecture diagram](https://lightspeed-core.github.io/lightspeed-stack/architecture.svg)
+[Architecture diagram](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/architecture.svg)
 
-## Installation and configuration
+[Installation on Linux](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/installation_linux.html)
 
+[Installation on MacOS](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/installation_macos.html)
 
-[Container Orchestration Guide](https://lightspeed-core.github.io/lightspeed-stack/container_orchestration.html)
-
-[Linux](https://lightspeed-core.github.io/lightspeed-stack/installation_linux.html)
-
-[MacOS](https://lightspeed-core.github.io/lightspeed-stack/installation_macos.html)
+[Database structure](https://lightspeed-core.github.io/lightspeed-stack/DB/index.html)
 
-## Status of Lightspeed Core Stack versions
+[Providers](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/providers.html)
 
-[Status of Lightspeed Core Stack versions](https://lightspeed-core.github.io/lightspeed-stack/version_status.html)
+[Container Orchestration Guide](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/container_orchestration.html)
 
-[Supported versions](https://lightspeed-core.github.io/lightspeed-stack/versions_supported.html)
+[Contributing guide](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/contributing_guide.html)
 
-[Unsupported versions](https://lightspeed-core.github.io/lightspeed-stack/versions_unsupported.html)
+### API
 
-## Migration guides
+[OpenAPI specification](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/openapi.html)
 
-[Migration guides](https://lightspeed-core.github.io/lightspeed-stack/migrations/)
+[Conversations API](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/conversations_api.html)
 
-## Info for developers
 
-[Contributing guide](https://lightspeed-core.github.io/lightspeed-stack/contributing_guide.html)
+## Maintenance
 
-## API
+[Status of Lightspeed Core Stack versions](https://lightspeed-core.github.io/lightspeed-stack/maintenance/version_status.html)
 
-[OpenAPI specification](https://lightspeed-core.github.io/lightspeed-stack/openapi.html)
+[Supported versions](https://lightspeed-core.github.io/lightspeed-stack/maintenance/versions_supported.html)
 
-[Conversations API](https://lightspeed-core.github.io/lightspeed-stack/conversations_api.html)
+[Unsupported versions](https://lightspeed-core.github.io/lightspeed-stack/maintenance/versions_unsupported.html)
 
-## RAG and BYOK
+## Migration guides
 
-## Other features
+[Migration guides](https://lightspeed-core.github.io/lightspeed-stack/migrations/)
 
-[Providers](https://lightspeed-core.github.io/lightspeed-stack/providers.html)
 
 [Sentry error tracking](https://lightspeed-core.github.io/lightspeed-stack/sentry.html)
 
 
-[Database structure](https://lightspeed-core.github.io/lightspeed-stack/DB/index.html)
 
 ## Models