added help files for YaCy UI web pages

5 files changed, 370 insertions, 0 deletions

diff --git a/help/api/citation.md b/help/api/citation.md
new file mode 100644
index 000000000..55ce68789
--- /dev/null
+++ b/help/api/citation.md
@@ -0,0 +1,74 @@
+---
+page: htroot/api/citation.html
+help: help/api/citation.md
+title: Document Citations for url
+package: machine-api-peer
+access: public
+kind: api-endpoint
+backend_java: source/net/yacy/htroot/api/citation.java
+---
+
+# Document Citations for url
+
+## Purpose
+
+Document Citations returns citation information for a URL or document.
+
+Use it when a tool needs references around one indexed document.
+
+## What You Can Do Here
+
+- Retrieve citation data for one URL or document.
+- Submit the exact document target.
+- Use the response to explain or reference indexed material.
+
+## Page Architecture
+
+Machine/API pages are compact endpoints. Their architecture is request-parameter driven: callers provide the smallest needed set of arguments and consume a direct response rather than a guided administration workflow.
+
+| Control | Meaning | Values or examples |
+| --- | --- | --- |
+| `filter` | List of ::Cited Sentences in. | `true::false` |
+
+## Correct Use
+
+Call the endpoint as a protocol surface. Use exact parameter names and encoded values, authenticate when required, and inspect the response before relying on it. Avoid sending browser-only submit buttons unless the backend explicitly requires the action key.
+
+## Access And Safety
+
+The page is normally public or read-only, unless the peer is configured to require authentication for all pages.
+
+## Automation And API
+
+Page backend: `source/net/yacy/htroot/api/citation.java`.
+
+| Endpoint | Method | Access | Backend |
+| --- | --- | --- | --- |
+| `/api/citation.html` | `POST` | public or page-dependent | `source/net/yacy/htroot/api/citation.java` |
+
+### Parameter Guide
+
+The table explains values that an agent or script must set deliberately. Parameters not relevant to a task should be omitted or left at the page default.
+
+| Parameter | Meaning and valid values | Care |
+| --- | --- | --- |
+| `filter` | Filter text or expression used to narrow the displayed records. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
+| `hash` | YaCy hash identifier for a peer, URL, row, or stored object. Use exact values copied from YaCy output. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `url` | URL to inspect, crawl, import, or act on. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+
+Example request shape:
+
+```http
+POST /api/citation.html
+Content-Type: application/x-www-form-urlencoded
+
+url=...&filter=...&ch=...&hash=...
+```
+
+## What To Expect
+
+Expect a compact service response rather than a teaching interface. The response may be XML, RSS, JSON-like text, plain text, or a small HTML template depending on the endpoint.
+
+## Related Pages
+
+- Related protocol work usually continues through the calling tool, the peer endpoint family under `/yacy/`, or the API page that consumes this response.
diff --git a/help/api/push_p.md b/help/api/push_p.md
new file mode 100644
index 000000000..55b9d5de0
--- /dev/null
+++ b/help/api/push_p.md
@@ -0,0 +1,77 @@
+---
+page: htroot/api/push_p.html
+help: help/api/push_p.md
+title: File Upload
+package: machine-api-peer
+access: admin
+kind: api-endpoint
+backend_java: source/net/yacy/htroot/api/push_p.java
+---
+
+# File Upload
+
+## Purpose
+
+File Upload accepts pushed content into YaCy.
+
+Use it when another tool submits documents directly instead of asking the crawler to fetch them.
+
+## What You Can Do Here
+
+- Push document content directly into YaCy.
+- Send file or document metadata in the expected upload shape.
+- Verify indexing afterward because upload acceptance is not the same as search visibility.
+
+## Page Architecture
+
+Machine/API pages are compact endpoints. Their architecture is request-parameter driven: callers provide the smallest needed set of arguments and consume a direct response rather than a guided administration workflow.
+
+| Control | Meaning | Values or examples |
+| --- | --- | --- |
+| `synchronous` | Choice value. Options: `true`. | `true` |
+| `commit` | Choice value. Options: `true`. | `true` |
+
+## Correct Use
+
+Call the endpoint as a protocol surface. Use exact parameter names and encoded values, authenticate when required, and inspect the response before relying on it. Avoid sending browser-only submit buttons unless the backend explicitly requires the action key.
+
+## Access And Safety
+
+Administrator access is required. YaCy protects `_p` pages as administration pages.
+
+Protected related endpoint(s): `/api/push_p.html`.
+
+## Automation And API
+
+Page backend: `source/net/yacy/htroot/api/push_p.java`.
+
+| Endpoint | Method | Access | Backend |
+| --- | --- | --- | --- |
+| `/api/push_p.html` | `POST` | admin | `source/net/yacy/htroot/api/push_p.java` |
+
+### Parameter Guide
+
+The table explains values that an agent or script must set deliberately. Parameters not relevant to a task should be omitted or left at the page default. Low-level generated parameters are omitted when they are only meaningful inside the rendered YaCy form.
+
+| Parameter | Meaning and valid values | Care |
+| --- | --- | --- |
+| `synchronous` | Choice value. Options: `true`. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `commit` | Choice value. Options: `true`. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `count` | SRU-style result count. It is an alternative to `maximumRecords` on search endpoints. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
+
+Example request shape:
+
+```http
+POST /api/push_p.html
+Content-Type: application/x-www-form-urlencoded
+
+synchronous=...&commit=...&data-#[count]#=...&url-#[count]#=...&collection-#[count]#=...
+```
+
+## What To Expect
+
+Expect a compact service response rather than a teaching interface. The response may be XML, RSS, JSON-like text, plain text, or a small HTML template depending on the endpoint.
+
+## Related Pages
+
+- Related protocol work usually continues through the calling tool, the peer endpoint family under `/yacy/`, or the API page that consumes this response.
diff --git a/help/api/share.md b/help/api/share.md
new file mode 100644
index 000000000..81d70afe1
--- /dev/null
+++ b/help/api/share.md
@@ -0,0 +1,70 @@
+---
+page: htroot/api/share.html
+help: help/api/share.md
+title: File Share
+package: machine-api-peer
+access: public
+kind: api-endpoint
+backend_java: source/net/yacy/htroot/api/share.java
+---
+
+# File Share
+
+## Purpose
+
+File Share exposes shared file content through an API-style page.
+
+Use it when another tool needs to retrieve a shared object from the peer.
+
+## What You Can Do Here
+
+- Retrieve or expose shared file content.
+- Use exact share identifiers and access parameters.
+- Confirm that shared material is intended to be visible.
+
+## Page Architecture
+
+Machine/API pages are compact endpoints. Their architecture is request-parameter driven: callers provide the smallest needed set of arguments and consume a direct response rather than a guided administration workflow.
+
+| Control | Meaning | Values or examples |
+| --- | --- | --- |
+
+## Correct Use
+
+Call the endpoint as a protocol surface. Use exact parameter names and encoded values, authenticate when required, and inspect the response before relying on it. Avoid sending browser-only submit buttons unless the backend explicitly requires the action key.
+
+## Access And Safety
+
+The page is normally public or read-only, unless the peer is configured to require authentication for all pages.
+
+## Automation And API
+
+Page backend: `source/net/yacy/htroot/api/share.java`.
+
+| Endpoint | Method | Access | Backend |
+| --- | --- | --- | --- |
+| `/api/share.html` | `POST` | public or page-dependent | `source/net/yacy/htroot/api/share.java` |
+
+### Parameter Guide
+
+The table explains values that an agent or script must set deliberately. Parameters not relevant to a task should be omitted or left at the page default. Low-level generated parameters are omitted when they are only meaningful inside the rendered YaCy form.
+
+| Parameter | Meaning and valid values | Care |
+| --- | --- | --- |
+
+Example request shape:
+
+```http
+POST /api/share.html
+Content-Type: application/x-www-form-urlencoded
+
+data=...&c=...
+```
+
+## What To Expect
+
+Expect a compact service response rather than a teaching interface. The response may be XML, RSS, JSON-like text, plain text, or a small HTML template depending on the endpoint.
+
+## Related Pages
+
+- Related protocol work usually continues through the calling tool, the peer endpoint family under `/yacy/`, or the API page that consumes this response.
diff --git a/help/api/table_p.md b/help/api/table_p.md
new file mode 100644
index 000000000..d6e96eef6
--- /dev/null
+++ b/help/api/table_p.md
@@ -0,0 +1,80 @@
+---
+page: htroot/api/table_p.html
+help: help/api/table_p.md
+title: Table Viewer
+package: machine-api-peer
+access: admin
+kind: api-endpoint
+backend_java: source/net/yacy/htroot/api/table_p.java
+---
+
+# Table Viewer
+
+## Purpose
+
+Table API exposes YaCy table data.
+
+Use it for scripted reads or writes of structured records when the table name and operation are known.
+
+## What You Can Do Here
+
+- Read or modify structured table data through the API surface.
+- Specify table names, keys, and operations exactly.
+- Check the response before assuming a row was created, changed, or deleted.
+
+## Page Architecture
+
+Machine/API pages are compact endpoints. Their architecture is request-parameter driven: callers provide the smallest needed set of arguments and consume a direct response rather than a guided administration workflow.
+
+| Control | Meaning | Values or examples |
+| --- | --- | --- |
+| `edittable` | Table: ''. | `Edit Table` |
+
+## Correct Use
+
+Call the endpoint as a protocol surface. Use exact parameter names and encoded values, authenticate when required, and inspect the response before relying on it. Avoid sending browser-only submit buttons unless the backend explicitly requires the action key.
+
+## Access And Safety
+
+Administrator access is required. YaCy protects `_p` pages as administration pages.
+
+Protected related endpoint(s): `/Tables_p.html`, `/api/table_p.html`.
+
+## Automation And API
+
+Page backend: `source/net/yacy/htroot/api/table_p.java`.
+
+| Endpoint | Method | Access | Backend |
+| --- | --- | --- | --- |
+| `/Tables_p.html` | `POST` | admin | `source/net/yacy/htroot/Tables_p.java` |
+| `/api/table_p.html` | `GET or POST` | admin | `source/net/yacy/htroot/api/table_p.java` |
+
+### Parameter Guide
+
+The table explains values that an agent or script must set deliberately. Parameters not relevant to a task should be omitted or left at the page default.
+
+| Parameter | Meaning and valid values | Care |
+| --- | --- | --- |
+| `edittable` | Table: ''. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `count` | SRU-style result count. It is an alternative to `maximumRecords` on search endpoints. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
+| `deleterows` | Deletion or termination action. Use only with explicit intent. | Can remove data, stop work, expose access, or make a broad operational change. Use only with explicit confirmation and an exact target. |
+| `deletetable` | Deletion or termination action. Use only with explicit intent. | Can remove data, stop work, expose access, or make a broad operational change. Use only with explicit confirmation and an exact target. |
+| `search` | Alternative search text parameter accepted by some search endpoints; prefer `query` on browser search pages unless reproducing an existing URL. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `table` | Table: ''. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+
+Example request shape:
+
+```http
+POST /Tables_p.html
+Content-Type: application/x-www-form-urlencoded
+
+edittable=...&addrow=...&commitrow=...&count=...&deleterows=...
+```
+
+## What To Expect
+
+Expect a compact service response rather than a teaching interface. The response may be XML, RSS, JSON-like text, plain text, or a small HTML template depending on the endpoint.
+
+## Related Pages
+
+- Related protocol work usually continues through the calling tool, the peer endpoint family under `/yacy/`, or the API page that consumes this response.
diff --git a/help/api/yacydoc.md b/help/api/yacydoc.md
new file mode 100644
index 000000000..f5c0e2c9c
--- /dev/null
+++ b/help/api/yacydoc.md
@@ -0,0 +1,69 @@
+---
+page: htroot/api/yacydoc.html
+help: help/api/yacydoc.md
+title: yacydoc
+package: machine-api-peer
+access: public
+kind: api-endpoint
+backend_java: source/net/yacy/htroot/api/yacydoc.java
+---
+
+# yacydoc
+
+## Purpose
+
+yacydoc exposes document data for tools.
+
+Use it when an agent needs a machine-oriented view of one indexed document.
+
+## What You Can Do Here
+
+- Retrieve machine-readable information about one indexed document.
+- Provide the exact URL, hash, or document identifier expected by the endpoint.
+- Use the response as document context for tools or citations.
+
+## Page Architecture
+
+This is a compact endpoint-style page. Its behavior is driven mainly by request parameters and the selected response template, so callers should send only the fields needed for the specific query or peer-service action.
+
+## Correct Use
+
+Call the endpoint as a protocol surface. Use exact parameter names and encoded values, authenticate when required, and inspect the response before relying on it. Avoid sending browser-only submit buttons unless the backend explicitly requires the action key.
+
+## Access And Safety
+
+The page is normally public or read-only, unless the peer is configured to require authentication for all pages.
+
+## Automation And API
+
+Page backend: `source/net/yacy/htroot/api/yacydoc.java`.
+
+| Endpoint | Method | Access | Backend |
+| --- | --- | --- | --- |
+| `/api/yacydoc.html` | `POST` | public or page-dependent | `source/net/yacy/htroot/api/yacydoc.java` |
+
+### Parameter Guide
+
+The table explains values that an agent or script must set deliberately. Parameters not relevant to a task should be omitted or left at the page default.
+
+| Parameter | Meaning and valid values | Care |
+| --- | --- | --- |
+| `url` | URL to inspect, crawl, import, or act on. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+| `urlhash` | YaCy URL hash identifying an indexed document. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
+
+Example request shape:
+
+```http
+POST /api/yacydoc.html
+Content-Type: application/x-www-form-urlencoded
+
+url=...&urlhash=...&html=...
+```
+
+## What To Expect
+
+Expect a compact service response rather than a teaching interface. The response may be XML, RSS, JSON-like text, plain text, or a small HTML template depending on the endpoint.
+
+## Related Pages
+
+- Related protocol work usually continues through the calling tool, the peer endpoint family under `/yacy/`, or the API page that consumes this response.