Documentation agent optimisation. Closes #20

.github/workflows/pr-preview.yml

@@ -12,31 +12,55 @@ permissions:
 concurrency:
   group: pr-preview-${{ github.event.pull_request.number }}
 
+env:
+  BUILD_PATH: "."
+  PREVIEW_HOST: "sentrie-pr-${{ github.event.pull_request.number }}.surge.sh"
+  PREVIEW_URL: "https://sentrie-pr-${{ github.event.pull_request.number }}.surge.sh"
+
 jobs:
   deploy-preview:
     name: Deploy Preview
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout code
+      - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Setup Node.js
+      - name: Detect package manager
+        id: detect-package-manager
+        run: |
+          if [ -f "${{ github.workspace }}/yarn.lock" ]; then
+            echo "manager=yarn" >> $GITHUB_OUTPUT
+            echo "command=install" >> $GITHUB_OUTPUT
+            echo "runner=yarn" >> $GITHUB_OUTPUT
+            echo "lockfile=yarn.lock" >> $GITHUB_OUTPUT
+            exit 0
+          elif [ -f "${{ github.workspace }}/package.json" ]; then
+            echo "manager=npm" >> $GITHUB_OUTPUT
+            echo "command=ci" >> $GITHUB_OUTPUT
+            echo "runner=npx --no-install" >> $GITHUB_OUTPUT
+            echo "lockfile=package-lock.json" >> $GITHUB_OUTPUT
+            exit 0
+          else
+            echo "Unable to determine package manager"
+            exit 1
+          fi
+
+      - name: Setup Node
         uses: actions/setup-node@v4
         with:
           node-version: "20"
-          cache: "npm"
+          cache: ${{ steps.detect-package-manager.outputs.manager }}
+          cache-dependency-path: ${{ env.BUILD_PATH }}/${{ steps.detect-package-manager.outputs.lockfile }}
 
       - name: Install dependencies
-        run: |
-          npm cache clean --force
-          rm -rf node_modules package-lock.json
-          npm install
+        run: ${{ steps.detect-package-manager.outputs.manager }} ${{ steps.detect-package-manager.outputs.command }}
+        working-directory: ${{ env.BUILD_PATH }}
 
-      - name: Build Astro site
-        env:
-          ASTRO_PREVIEW: "true"
-          ASTRO_SITE_URL: "https://sentrie-pr-${{ github.event.pull_request.number }}.surge.sh"
-        run: npm run build
+      - name: Build with Astro
+        run: |
+          ${{ steps.detect-package-manager.outputs.runner }} astro build \
+            --site "${{ env.PREVIEW_URL }}"
+        working-directory: ${{ env.BUILD_PATH }}
 
       - name: Install Surge
         run: npm install --global surge
@@ -46,10 +70,9 @@ jobs:
           SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }}
         run: |
           cd dist
-          PREVIEW_DOMAIN="sentrie-pr-${{ github.event.pull_request.number }}.surge.sh"
           for i in {1..10}; do
             if surge --project . \
-              --domain "$PREVIEW_DOMAIN" \
+              --domain "${{ env.PREVIEW_HOST }}" \
               -y; then
               echo "Surge deploy succeeded!"
               break
@@ -61,16 +84,14 @@ jobs:
               exit 1
             fi
           done
-
 
       - name: Verify deployment
         timeout-minutes: 2
         run: |
-          PREVIEW_URL="https://sentrie-pr-${{ github.event.pull_request.number }}.surge.sh"
-          echo "Verifying deployment at $PREVIEW_URL..."
+          echo "Verifying deployment at ${{ env.PREVIEW_URL }}..."
           for i in {1..10}; do
-            if curl -fsSL -o /dev/null "$PREVIEW_URL"; then
-              echo "Deployment verified successfully!"
+            if curl -fsSL -o /dev/null "${{ env.PREVIEW_URL }}"; then
+              echo "Deployment verified successfully at ${{ env.PREVIEW_URL }}!"
               exit 0
             fi
             echo "Attempt $i/10 failed, retrying in 2 seconds..."
@@ -97,8 +118,8 @@ jobs:
             <!-- surge-preview -->
             ## 🚀 Preview Deployment
 
-            A preview of this PR has been deployed to:
+            A preview of this PR has been deployed to ${{ env.PREVIEW_URL }}:
 
-            🔗 **[View Preview](https://sentrie-pr-${{ github.event.pull_request.number }}.surge.sh)**
+            🔗 **[View Preview](${{ env.PREVIEW_URL }}) at ${{ env.PREVIEW_URL }}**
 
             This preview will be automatically removed when the PR is merged or closed.

astro.config.mjs

@@ -27,21 +27,11 @@ export default defineConfig({
           label: "Getting Started",
           items: [
             {
-              label: "What is Sentrie?",
-              slug: "getting-started/what-is-sentrie",
-            },
-            {
-              label: "What is Policy as Code?",
-              slug: "getting-started/what-is-policy-as-code",
-            },
-            {
-              label: "Why Sentrie?",
-              slug: "getting-started/why-sentrie",
-            },
-            {
-              label: "Installation",
-              slug: "getting-started/installation",
+              label: "Introduction & Core Philosophy",
+              slug: "getting-started/introduction",
             },
+            { label: "Quick Start", slug: "getting-started/quick-start" },
+            { label: "Installation", slug: "getting-started/installation" },
             {
               label: "Writing your first Policy",
               slug: "getting-started/writing-your-first-policy",
@@ -50,34 +40,37 @@ export default defineConfig({
               label: "Running your Policy",
               slug: "getting-started/running-your-policy",
             },
-            {
-              label: "Policy Enforcement",
-              slug: "getting-started/enforcement",
-            },
+            { label: "Enforcement", slug: "getting-started/enforcement" },
           ],
         },
         {
-          label: "Structure of a Policy Pack",
+          label: "Guides",
           items: [
+            { label: "Testing Policies", slug: "guides/testing-policies" },
             {
-              label: "Overview",
-              slug: "structure-of-a-policy-pack/overview",
+              label: "Policy Design Best Practices",
+              slug: "guides/policy-design-best-practices",
             },
             {
-              label: "Pack File",
-              slug: "structure-of-a-policy-pack/packfile",
+              label: "Deployment and Security",
+              slug: "guides/deployment-and-security",
             },
+          ],
+        },
+        {
+          label: "Language Concepts",
+          items: [
             {
-              label: "Program File",
-              slug: "structure-of-a-policy-pack/program-file",
+              label: "Type System & Shapes Overview",
+              slug: "language-concepts/type-system-shapes",
             },
             {
-              label: "TypeScript File",
-              slug: "structure-of-a-policy-pack/typescript-file",
+              label: "Policy Composition",
+              slug: "language-concepts/policy-composition",
             },
             {
-              label: "Example Pack",
-              slug: "structure-of-a-policy-pack/example-pack",
+              label: "Pattern Matching & Conditionals",
+              slug: "language-concepts/pattern-matching-conditionals",
             },
           ],
         },
@@ -101,6 +94,10 @@ export default defineConfig({
               label: "Overview",
               slug: "reference",
             },
+            {
+              label: "Identifiers",
+              slug: "reference/identifiers",
+            },
             {
               label: "Types and Values",
               slug: "reference/types-and-values",
@@ -153,6 +150,10 @@ export default defineConfig({
               label: "Boolean Operations",
               slug: "reference/boolean-operations",
             },
+            {
+              label: "Membership Operations",
+              slug: "reference/membership-operations",
+            },
             {
               label: "Using Functions",
               slug: "reference/functions",
@@ -173,6 +174,10 @@ export default defineConfig({
               label: "Precedence",
               slug: "reference/precedence",
             },
+            {
+              label: "Errors",
+              slug: "reference/errors",
+            },
             {
               label: "Security and Permissions",
               slug: "reference/security-and-permissions",
@@ -182,10 +187,7 @@ export default defineConfig({
         {
           label: "TypeScript Modules",
           items: [
-            {
-              label: "Overview",
-              slug: "reference/typescript_modules",
-            },
+            { label: "Overview", slug: "reference/typescript_modules" },
             {
               label: "JavaScript Globals",
               slug: "reference/typescript_modules/sentrie/js",
@@ -210,14 +212,8 @@ export default defineConfig({
               label: "JSON",
               slug: "reference/typescript_modules/sentrie/json",
             },
-            {
-              label: "JWT",
-              slug: "reference/typescript_modules/sentrie/jwt",
-            },
-            {
-              label: "Net",
-              slug: "reference/typescript_modules/sentrie/net",
-            },
+            { label: "JWT", slug: "reference/typescript_modules/sentrie/jwt" },
+            { label: "Net", slug: "reference/typescript_modules/sentrie/net" },
             {
               label: "Regex",
               slug: "reference/typescript_modules/sentrie/regex",
@@ -230,38 +226,45 @@ export default defineConfig({
               label: "Time",
               slug: "reference/typescript_modules/sentrie/time",
             },
-            {
-              label: "URL",
-              slug: "reference/typescript_modules/sentrie/url",
-            },
+            { label: "URL", slug: "reference/typescript_modules/sentrie/url" },
             {
               label: "UUID",
               slug: "reference/typescript_modules/sentrie/uuid",
             },
           ],
         },
         {
-          label: "CLI Reference",
+          label: "Extensibility",
           items: [
             {
-              label: "Overview",
-              slug: "cli-reference",
-            },
-            {
-              label: "init",
-              slug: "cli-reference/init",
-            },
-            {
-              label: "exec",
-              slug: "cli-reference/exec",
-            },
-            {
-              label: "serve",
-              slug: "cli-reference/serve",
+              label: "Writing Custom TypeScript Modules",
+              slug: "extensibility/writing-custom-typescript-modules",
             },
+          ],
+        },
+        {
+          label: "CLI Reference",
+          items: [
+            { label: "Overview", slug: "cli-reference" },
+            { label: "sentrie exec", slug: "cli-reference/exec" },
+            { label: "sentrie init", slug: "cli-reference/init" },
+            { label: "sentrie serve", slug: "cli-reference/serve" },
+            { label: "sentrie validate", slug: "cli-reference/validate" },
+          ],
+        },
+        {
+          label: "Troubleshooting",
+          items: [
+            { label: "Overview", slug: "troubleshooting" },
+            { label: "Common Errors", slug: "troubleshooting/common-errors" },
+          ],
+        },
+        {
+          label: "Deployment & Operations",
+          items: [
             {
-              label: "validate",
-              slug: "cli-reference/validate",
+              label: "Running as a Service",
+              slug: "deployment-operations/running-as-service",
             },
           ],
         },

docs-template.md

@@ -0,0 +1,50 @@
+# [Feature Name]
+
+[A short, conversational paragraph explaining what this is and the exact problem it solves. Write as if you are explaining it to a colleague. Focus on the "why"—e.g., "When you need to guarantee the exact structure of an incoming payload before evaluating it, use Shapes."]
+
+Here is the basic syntax:
+
+```typescript
+// The formal definition or type signature
+```
+
+## Configuration & Arguments
+
+[A brief, friendly sentence setting up the table, e.g., "You can customize the behavior using the following parameters:"]
+
+| Argument    | Type   | Required | What it does                                  |
+| :---------- | :----- | :------- | :-------------------------------------------- |
+| `paramName` | `Type` | Yes/No   | A plain-English explanation of this argument. |
+
+**Returns:** `ReturnType` — [Explain what the developer gets back in plain English, e.g., "A validated object, or it aborts the evaluation if constraints fail."]
+
+---
+
+## Examples in Action
+
+### [Scenario 1: e.g., Validating a standard user profile]
+
+[One to two sentences explaining the real-world context of this example. Why would a developer actually write this?]
+
+```typescript
+// Clean, copy-pasteable code using realistic variable names
+// like userAge or billingAddress instead of foo and bar.
+```
+
+### [Scenario 2: e.g., Handling complex nested objects]
+
+[Context for the advanced use case. What edge case or complexity does this solve?]
+
+```typescript
+// Advanced example code showing composition or error handling.
+```
+
+---
+
+## Good to Know
+
+Before you implement this, keep a few boundaries in mind to ensure predictable execution:
+
+- **[Constraint]:** [e.g., "Sentrie evaluates these strictly. If an incoming payload includes keys not defined in your Shape, the evaluation will fail."]
+- **[Performance tip]:** [e.g., "If you are validating deeply nested JSON, keep your recursion depth under X for optimal performance."]
+- **[Edge case]:** [e.g., "Null values are only accepted if you explicitly use the `.nullable()` modifier."]