docs: Update based on slack feedback (#7990)

* docs: Update policy-reference page with intro

I hope this addresses some of the pain shared in:
https://openpolicyagent.slack.com/archives/C08V59T3NAF/p1761232592164519

Signed-off-by: Charlie Egan <charlie_egan@apple.com>

* docs: Revise server, net, port diagram

We had some valid feedback that this was disjointed with the following
text.

https://openpolicyagent.slack.com/archives/C08V59T3NAF/p1761298015276409

Signed-off-by: Charlie Egan <charlie_egan@apple.com>

* docs: Correct typo in keyword link

Signed-off-by: Charlie Egan <charlie_egan@apple.com>

---------

Signed-off-by: Charlie Egan <charlie_egan@apple.com>

docs/docs/index.md

@@ -46,17 +46,21 @@ Let's look at an example. Imagine you work for an organization with the followin
 
 ```mermaid
 graph
-    nX["Public Network X"] --> Internet
-    nY["Private Network Y"]
-    sX["Server X"] --"Port X"--> nX
-    sY["Server Y"] --"Port X"--> nX
-    sY --"Port Y"--> nY
-    sZ["Server Z"] --"Port Z"--> nY
+    n1["net1 (private)"]
+    n2["net2 (private)"]
+    n3["net3 (public)"] --> Internet
+    sCI["ci"] --"p1"--> n1
+    sCI --"p2"--> n2
+    sBusy["busybox"] --"p1"--> n3
+    sApp["app"] --"p1"--> n3
+    sApp --"p2"--> n1
+    sApp --"p3"--> n2
+    sCache["cache"] --"p3"--> n2
 ```
 
 There are three kinds of components in the system:
 
-- Servers expose zero or more protocols (e.g., `http`, `ssh`, etc.)
+- Servers listen on a range of ports (for different protocols such as `http`, `ssh`, etc.)
 - Networks connect servers and can be public or private. Public networks are connected to the Internet.
 - Ports attach servers to networks.
 

docs/docs/policy-reference/index.md

@@ -8,6 +8,15 @@ import BuiltinLegacyRedirect from "@site/src/components/BuiltinLegacyRedirect";
 
 <BuiltinLegacyRedirect/>
 
+This page is a reference for details of the Rego language and its syntax. See
+our guided [Policy Language](./policy-language) page for a walked introduction.
+There are also detailed sections for
+[built-in functions](./policy-reference/builtins) as well as examples for
+specific keywords such as
+[`contains`](./policy-reference/keywords/contains),
+[`if`](./policy-reference/keywords/if) and
+[`default`](./policy-reference/keywords/default).
+
 ## Assignment and Equality
 
 ```rego
@@ -322,43 +331,50 @@ as defining partial sets, like `box2`.
 ## Tests
 
 ```rego
-# define a rule that starts with test_
+# it's common for tests to have a _test in their package name
+package foo.bar_test # contains tests for package foo.bar
+
+# define a rule that starts with test_, these will be run with opa test
 test_NAME { ... }
 
-# override input.foo value using the 'with' keyword
+# override input.foo value using the 'with' keyword to mock different inputs
 data.foo.bar.deny with input.foo as {"bar": [1,2,3]}}
 ```
 
+:::tip
+Please see [Policy Testing](./policy-testing) for an in depth look into writing
+and running Rego tests with OPA.
+:::
+
 ## Built-in Functions
 
 Rego's built-in functions offer policy authors tools for common policy
 operations like JWT validation, signature verification, among many others.
-The reference documentation for these functions can be found under [Built-in Functions](./policy-reference/builtins).
+The reference documentation for these functions can be found under
+[Built-in Functions](./policy-reference/builtins).
 
-## Reserved Names
+## Reserved Names & Keywords
 
 The following words are reserved and cannot be used as variable names, rule
 names, or dot-access style reference arguments:
 
-```
-as
-contains
-data
-default
-else
-every
-false
-if
-in
-import
-input
-package
-not
-null
-some
-true
-with
-```
+- `as`
+- `contains` ([Examples](./policy-reference/keywords/contains))
+- `data`
+- `default` ([Examples](./policy-reference/keywords/default))
+- `else`
+- `every` ([Examples](./policy-reference/keywords/every))
+- `false`
+- `if` ([Examples](./policy-reference/keywords/if))
+- `in`
+- `import` ([Examples](./policy-reference/keywords/import))
+- `input`
+- `package`
+- `not` ([Examples](./policy-reference/keywords/not))
+- `null`
+- `some` ([Examples](./policy-reference/keywords/some))
+- `true`
+- `with`
 
 ## Grammar
 

docs/package.json

@@ -10,11 +10,11 @@
   "license": "ISC",
   "description": "",
   "dependencies": {
-    "@docusaurus/core": "^3.9.1",
-    "@docusaurus/plugin-content-docs": "^3.9.1",
-    "@docusaurus/plugin-google-gtag": "^3.9.1",
-    "@docusaurus/preset-classic": "^3.9.1",
-    "@docusaurus/theme-mermaid": "^3.9.1",
+    "@docusaurus/core": "^3.9.2",
+    "@docusaurus/plugin-content-docs": "^3.9.2",
+    "@docusaurus/plugin-google-gtag": "^3.9.2",
+    "@docusaurus/preset-classic": "^3.9.2",
+    "@docusaurus/theme-mermaid": "^3.9.2",
     "@easyops-cn/docusaurus-search-local": "^0.49.2",
     "@iconify/react": "^6.0.0",
     "@mermaid-js/layout-elk": "^0.1.9",