Improve Solid usage descriptions

Author: rubensworks

package.json

@@ -23,5 +23,6 @@
     "remark-gfm": "^1.0.0",
     "rss": "^1.2.2",
     "sass": "^1.26.10"
-  }
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

pages/docs/1_query/advanced/solid.md

@@ -12,23 +12,58 @@ Solid achieves this by giving everyone control over their own **personal data po
 Applications are completely separate, and have to ask permission to access your data.
 
 Since Solid and Comunica have a compatible technology stack,
-Comunica can be used to query over Solid data pods.
-The default [Comunica SPARQL engine](/docs/query/getting_started/query_cli/)
-can directly be used to query over public Solid data pods as long as you are querying over public data.
-If you want to **query over data pods that require authentication**,
-you can use one of the approaches mentioned below.
+Comunica can be used to query over one or more Solid data pods.
 
-## Query pods with a custom fetch function
+This document describes the different approaches that exist for querying Solid pods using Comunica.
 
-Libraries such as [@inrupt/solid-client-authn-node](https://www.npmjs.com/package/@inrupt/solid-client-authn-node)
-and [@inrupt/solid-client-authn-browser](https://www.npmjs.com/package/@inrupt/solid-client-authn-browser)
-allow you to authenticate with your Solid WebID.
+In summary, there are three main approaches for querying Solid pods with Comunica:
+1. **Query specific public documents**: Comunica SPARQL (`@comunica/query-sparql`)
+2. **Query specific private documents**: Comunica SPARQL (`@comunica/query-sparql`) and pass authenticated fetch function, or Comunica SPARQL Solid (`@comunica/query-sparql-solid`)
+3. **Query pods using link traversal** (_experimental_): Comunica SPARQL Link Traversal Solid (`@comunica/query-sparql-link-traversal-solid`)
+
+## 1. Query specific public documents in Solid pods
+
+If you have prior knowledge of what documents in a Solid pod contain the data you want to query over,
+and these documents do not require authentication,
+then you can directly query over these documents using the default [Comunica SPARQL engine](/docs/query/getting_started/query_cli/)
+as a traditional federated query.
+
+**Querying from JavaScript**:
+```typescript
+import { QueryEngine } from '@comunica/query-sparql';
+
+const myEngine = new QueryEngine();
+
+const bindingsStream = await myEngine.queryBindings(`
+  SELECT * { ?s ?p ?o }`, {
+  sources: ['https://pod1.org/document1.ttl', 'https://pod2.org/document2.ttl'],
+});
+```
+
+**Querying from the command line**:
+```bash
+$ comunica-sparql https://pod1.org/document1.ttl https://pod2.org/document2.ttl \
+    "SELECT * { ?s ?p ?o }"
+```
+
+<div class="note">
+While the examples above show querying over multiple documents in Solid pods,
+<a href="/docs/query/advanced/source_types/">other types of sources</a> (such as SPARQL endpoints, RDF files, etc.) can also be used in combination with Solid pods in the same query.
+</div>
+
+## 2. Query specific private documents in Solid pods
+
+Similar to the previous approach, you can also query specific documents in Solid pods that require authentication.
+
+For this, you can use Comunica in combination with libraries such as [@inrupt/solid-client-authn-node](https://www.npmjs.com/package/@inrupt/solid-client-authn-node)
+and [@inrupt/solid-client-authn-browser](https://www.npmjs.com/package/@inrupt/solid-client-authn-browser) that allow you to authenticate with your Solid WebID.
 These libraries provide a custom `fetch` function, using which you can execute authenticated HTTP requests.
 
 You can forward this fetch function to Comunica SPARQL to make it perform authenticated queries to pods as shown below.
 
+**Querying from JavaScript with Comunica SPARQL**:
 ```typescript
-import { QueryEngine } from '@comunica/query-sparql-solid';
+import { QueryEngine } from '@comunica/query-sparql';
 import { Session } from '@inrupt/solid-client-authn-node';
 
 const session = new Session();
@@ -47,15 +82,19 @@ const bindingsStream = await myEngine.queryBindings(`
 });
 ```
 
-## Query pods with an existing Solid session
+<div class="note">
+You can also try out authenticated queries to your Solid pods via our
+<a href="https://query.comunica.dev/">live web client</a>.
+To enable authentication, click the gear icon, fill in your Identity Provider, and press the "Log in" button.
+</div>
 
-[Comunica SPARQL Solid](https://github.com/comunica/comunica-feature-solid/tree/master/engines/query-sparql-solid)
-allows you to pass your authenticated Solid session object.
+Alternatively, you can use the dedicated [Comunica SPARQL Solid](https://github.com/comunica/comunica-feature-solid/tree/master/engines/query-sparql-solid),
+which allows you to pass your authenticated Solid session object.
 Hereafter, we list some examples on how to use it from JavaScript and the command line.
 Please refer to the [README of Comunica SPARQL Solid](https://github.com/comunica/comunica-feature-solid/tree/master/engines/query-sparql-solid#readme)
 for more details.
 
-**Querying from JavaScript**:
+**Querying from JavaScript Comunica SPARQL Solid**:
 ```typescript
 import { QueryEngine } from '@comunica/query-sparql-solid';
 import { Session } from '@inrupt/solid-client-authn-node';
@@ -101,21 +140,21 @@ Please be aware that that there are several [open known issues](https://github.c
 
 [LDflex](/docs/query/usage/#ldflex) and [GraphQL-LD](/docs/query/usage/#graphql-ld) are examples of tools that ship with Comunica SPARQL Solid.
 
-## Query pods using link traversal
+## 3. Query pods using link traversal
 
 The approaches for querying Solid mentioned above require you to know upfront in which pod and in which documents
 your data resides before you can query over it.
 [_Comunica SPARQL Link Traversal Solid_](https://github.com/comunica/comunica-feature-link-traversal/tree/master/engines/query-sparql-link-traversal-solid#comunica-sparql-link-traversal)
 provides a way to query over Solid pods without having to know beforehand in which documents the necessary data resides in.
 It does this by following links between documents _during query execution_.
 
-This is still an experimental query approach, which does not yet work well for complex queries.
+This is still an **experimental query approach**, which does not yet work well for complex queries.
 Learn more about active [research on link traversal in Solid](https://comunica.dev/research/link_traversal/).
 
 The example below executes a query across multiple simulated Solid pods to find all messages by a certain creator:
 
 ```typescript
-import { QueryEngine } from '@comunica/query-sparql-solid';
+import { QueryEngine } from '@comunica/query-sparql-link-traversal-solid';
 
 const myEngine = new QueryEngine();
 const bindingsStream = await myEngine.queryBindings(`

pages/index.js

@@ -53,6 +53,16 @@ export default function Home() {
             <p>Learn how to configure or extend</p>
           </a>
 
+          <a href="docs/query/advanced/solid" className="card">
+            <h3>Query Solid pods &rarr;</h3>
+            <p>Query one or more Solid pods</p>
+          </a>
+
+          <a href="docs/query/advanced/mcp/" className="card">
+            <h3>Comunica MCP &rarr;</h3>
+            <p>Connect Comunica with AI Agents</p>
+          </a>
+
           <a href="https://opencollective.com/comunica-association" className="card">
             <h3>Donate &rarr;</h3>
             <p>Sponsor via Open Collective</p>