docs: add naming convention for flows and trails (#593)

* add naming convention for flows and trails
* avoid confusion with org as Kosli org
* fix typo

Author: dangrondahl

docs.kosli.com/content/implementation_guide/phase_2/_index.md

@@ -0,0 +1,5 @@
+---
+title: "Phase 2: Configure Kosli"
+bookCollapseSection: true
+weight: 200
+---

docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/_index.md

@@ -0,0 +1,6 @@
+---
+title: "Plan Organizational Structure"
+bookCollapseSection: true
+weight: 100
+---
+

docs.kosli.com/content/implementation_guide/phase_2/plan_organizational_structure/naming_conventions.md

@@ -0,0 +1,199 @@
+---
+title: "Naming Conventions"
+bookCollapseSection: false
+weight: 200
+---
+
+# Naming Conventions
+
+Clear and consistent naming makes it easy for everyone to understand what each item in Kosli represents. Good names help you route attestations correctly and quickly find what you need.
+
+Use these conventions for:
+- **Flows** and **Trails**
+- **Attestation Types**
+- **Environments**
+
+## General Guidelines
+
+The general guidelines should be considered best practices for all naming conventions in Kosli. You can adapt them to fit your organization’s needs, but consistency is key.
+
+All of our proposed conventions follow these general guidelines:
+
+**Structure**: `<element 1>` `<delimiter>` `<element 2>` `<delimiter>`...`<element N>`
+
+
+1. **Choose Delimiter**: Choose a delimiter that works for your and stick with it consistently.</br>
+For example hyphen `-`, underscore `_`, tilde `~` or dot `.`. </br>
+Avoid mixing delimiters within the same naming scheme.
+2. **Choose case style for elements**: Choose a meaningful case style across elements (e.g., PascalCase, camelCase, snake_case) and use it consistently. Avoid spaces and clashes with delimiters.
+3. **Keep it concise**: Shorter names are easier to read and remember. Aim for concise but descriptive names.
+4. **Avoid special characters**: Stick to alphanumeric characters and underscores/hyphens
+
+{{% hint warning %}}
+Be aware of using underscore `_` as the delimiter, as that conflicts with snake_case for elements.
+{{% /hint %}}
+
+{{% hint info %}}
+The rest of this document uses hyphen `-` as the delimiter in examples, but you can choose any delimiter that fits your needs.
+{{% /hint %}}
+
+### Regular Expression
+
+To help enforce these conventions programmatically, here are sample regular expressions you can use based on your chosen case style.
+
+Adjust the regex if you choose a different delimiter.
+
+{{< tabs "naming-regex" >}}
+{{< tab "snake_case" >}}
+
+**Example**: `element_one`-`element_two`-`element_three`
+
+```bash
+^[a-z][a-z0-9_]*(-[a-z][a-z0-9_]*)*$
+```
+
+{{< /tab >}}
+{{< tab "camelCase" >}}
+
+**Example**: `elementOne`-`elementTwo`-`elementThree`
+
+```bash
+^[a-z][a-zA-Z0-9]*(-[a-z][a-zA-Z0-9]*)*$
+```
+
+{{< /tab >}}
+{{< tab "PascalCase" >}}
+
+**Example**: `ElementOne`-`ElementTwo`-`ElementThree`
+
+```bash
+^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+
+{{% hint info %}}
+If you want a specific length limit (e.g., max 50 characters), you can add a lookahead at the start of the regex:
+
+```bash
+^(?=.{1,50}$) # + rest of the regex
+```
+
+You can use online regex testers like [regex101](https://regex101.com/) to validate and test these expressions.
+
+{{% /hint %}}
+
+## Flows
+
+A clear naming convention transforms a simple ID into a meaningful identifier that everyone understands. This shared language ensures attestations go to the right place and you can track your releases from start to finish.
+
+### Build Flows
+
+Build Flows represent how code changes move from commit to artifact. Use the following convention to name Build Flows:
+
+**Name Convention:** `org-unit`-`repo`-`[service]`
+
+- **org-unit**: Your organizational unit, division or team name
+- **repo**: Your repository name
+- **service (Optional)**: The specific service or component that the artifact belongs to
+
+{{% hint info %}}
+You can skip `service` if your repository produces only one artifact, i.e. non-monorepo setups.
+{{% /hint %}}
+
+{{< tabs "build-flow-examples" >}}
+{{< tab "snake_case" >}}
+
+**Examples:**
+- `investment-web_app` (single artifact)
+- `investment-web_app-frontend` (with service: frontend)
+- `devops_team-mobile_app-backend` (with service: backend)
+
+```bash
+^[a-z][a-z0-9_]*-[a-z][a-z0-9_]*(-[a-z][a-z0-9_]*)?$
+```
+
+{{< /tab >}}
+{{< tab "camelCase" >}}
+
+**Examples:**
+- `investment-webApp` (single artifact)
+- `investment-webApp-frontend` (with service: frontend)
+- `devopsTeam-mobileApp-backend` (with service: backend)
+
+```bash
+^[a-z][a-zA-Z0-9]*-[a-z][a-zA-Z0-9]*(-[a-z][a-zA-Z0-9]*)?$
+```
+{{< /tab >}}
+{{< tab "PascalCase" >}}
+
+**Examples:**
+- `Investment-WebApp` (single artifact)
+- `Investment-WebApp-Frontend` (with service: frontend)
+- `DevOpsTeam-MobileApp-Backend` (with service: backend)
+
+```bash
+^[A-Z][a-zA-Z0-9]*-[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)?$
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Release Flows
+
+Release Flows represent how artifacts move from build to deployment. Use the following convention to name Release Flows:
+
+**Name Convention:** `org-unit`-`repo`
+
+- **org-unit**: Your organizational unit, division or team name
+- **repo**: Your repository name
+
+{{< tabs "release-flow-examples" >}}
+{{< tab "snake_case" >}}
+**Examples:**
+- `investment-web_app`
+- `devops_team-mobile_app`
+```bash
+^[a-z][a-z0-9_]*-[a-z][a-z0-9_]*$
+```
+{{< /tab >}}
+{{< tab "camelCase" >}}
+**Examples:**
+- `investment-webApp`
+- `devopsTeam-mobileApp`
+```bash
+^[a-z][a-zA-Z0-9]*-[a-z][a-zA-Z0-9]*$
+```
+{{< /tab >}}
+{{< tab "PascalCase" >}}
+**Examples:**
+- `Investment-WebApp`
+- `DevOpsTeam-MobileApp`
+```bash
+^[A-Z][a-zA-Z0-9]*-[A-Z][a-zA-Z0-9]*$
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+
+## Trails
+
+### Trails associated with [Build Flows]({{< ref "#build-flows" >}})
+
+**Name Convention:** `sha`
+
+- **sha**: The git commit HEAD SHA that triggered the build.
+
+### Trails associated with [Release Flows]({{< ref "#release-flows" >}})
+**Name Convention:** `env`-`pr-number`
+
+- **env**: The target deployment environment (e.g., staging, production)
+- **pr-number**: The pull request or change request number associated with the deployment.
+
+**Examples:**
+- `staging-42`
+- `production-108`
+
+```bash
+^[a-z][a-z0-9_]*-[0-9]+$
+```