chore: fixing minor docs issues

docs/csit/csit.md

@@ -1,8 +1,6 @@
 # Continuous System Integration Testing
 
-The Agncty Continuous System Integration Testing (CSIT) system design needs to
-meet the continuously expanding requirements of Agntcy projects including Agent
-Gateway Protocol, Agent Directory, and others.
+The Agncty Continuous System Integration Testing (CSIT) system design needs to meet the continuously expanding requirements of Agntcy projects, such as the [Agent Directory Service](../dir/overview.md).
 
 Tests can be run locally using taskfile or in GitHub Actions.
 

docs/dir/getting-started.md

@@ -103,6 +103,11 @@ This starts the necessary components such as storage and API services.
 DIRECTORY_SERVER_OASF_API_VALIDATION_SCHEMA_URL=https://schema.oasf.outshift.com task server:start
 ```
 
+!!! note
+
+    MacOS users may encounter a "port 5000 already in use" error. This is likely caused by the AirPlay Receiver feature. You can disable it in your System Settings.
+
+
 ### Using Helm chart
 
 This deploys Directory services into an existing Kubernetes cluster.
@@ -112,15 +117,64 @@ helm pull oci://ghcr.io/agntcy/dir/helm-charts/dir --version v0.3.0
 helm upgrade --install dir oci://ghcr.io/agntcy/dir/helm-charts/dir --version v0.3.0
 ```
 
+Alternatively, you can configure the OASF schema URL explicitly:
+
+```bash
+helm upgrade --install dir oci://ghcr.io/agntcy/dir/helm-charts/dir --version v0.3.0 \
+  --set apiserver.config.oasf_api_validation.schema_url=https://schema.oasf.outshift.com
+```
+
+Or create a `values.yaml` file:
+
+```yaml
+apiserver:
+  config:
+    oasf_api_validation:
+      schema_url: "https://schema.oasf.outshift.com"
+```
+
+Then deploy:
+
+```bash
+helm upgrade --install dir oci://ghcr.io/agntcy/dir/helm-charts/dir --version v0.3.0 -f values.yaml
+```
+
+For more configuration options, see the [Validation](validation.md) documentation.
+
 ### Using Docker Compose
 
-This deploys Directory services using Docker Compose:
+This deploys Directory services using Docker Compose.
+
+ While the Directory server has a default OASF schema URL, Docker Compose deployments may require explicitly setting the `DIRECTORY_SERVER_OASF_API_VALIDATION_SCHEMA_URL` environment variable:
 
 ```bash
 cd install/docker
+export DIRECTORY_SERVER_OASF_API_VALIDATION_SCHEMA_URL=https://schema.oasf.outshift.com
 docker compose up -d
 ```
 
+Alternatively, you can disable API validation (not recommended for production):
+
+```bash
+cd install/docker
+export DIRECTORY_SERVER_OASF_API_VALIDATION_DISABLE=true
+docker compose up -d
+```
+
+For more configuration options, see the [Validation](validation.md) documentation.
+
+## Next Steps
+
+Now that you have the Directory services running, you can start using the Directory CLI to create and store your first agent record. See the [Directory CLI Reference](directory-cli.md) for more information.
+
+For detailed use cases, see the [Features and Usage Scenarios](scenarios.md) documentation, includng:
+
+- [Building Records](scenarios.md#build)
+- [Storing Records](scenarios.md#store)
+- [Signing and Verifying Records](scenarios.md#signing-and-verification)
+- [Discovering Records](scenarios.md#discover)
+- [Searching Records](scenarios.md#search)
+
 ## Directory MCP Server
 
 The Directory services are also accessible through the Directory MCP Server. It provides a standardized interface for AI assistants and tools to interact with the Directory system and work with OASF agent records. See the [Directory CLI Reference](directory-cli.md#directory-mcp-server) for more information.

docs/dir/validation.md

@@ -3,15 +3,21 @@
 The Directory enforces validation on all records before accepting them.
 Validation is performed using the [OASF SDK](../oasf/oasf-sdk.md), which requires an OASF schema server URL for validation.
 
-## Required Configuration
+## Configuration
 
-The Directory server requires an OASF schema URL to start. You must provide a valid OASF schema server URL for validation to work:
+The Directory server validates records using an OASF schema URL. By default, it uses `https://schema.oasf.outshift.com`, but you can configure a different OASF instance:
+
+**Using environment variables:**
 
 ```bash
-DIRECTORY_SERVER_OASF_API_VALIDATION_SCHEMA_URL=https://schema.oasf.outshift.com task server:start
+# Use default OASF instance (https://schema.oasf.outshift.com)
+task server:start
+
+# Use custom OASF instance
+DIRECTORY_SERVER_OASF_API_VALIDATION_SCHEMA_URL=https://your-custom-oasf.com task server:start
 ```
 
-The configuration can also be set via YAML file:
+**Using YAML configuration:**
 
 ```yaml
 # server.config.yml
@@ -20,6 +26,10 @@ oasf_api_validation:
 listen_address: "0.0.0.0:8888"
 ```
 
+!!! note
+
+    The server itself does not have a built-in default schema URL. Deployment tools like Helm and Taskfile set `https://schema.oasf.outshift.com` as the default. When using Docker Compose or running the server binary directly, you must explicitly set the `DIRECTORY_SERVER_OASF_API_VALIDATION_SCHEMA_URL` environment variable.
+
 ## Validation Behavior
 
 The Directory server uses API-based validation against the configured OASF schema server: