ecmind-blue-studio 1.0.0__tar.gz

ecmind_blue_studio-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ECMind GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ecmind_blue_studio-1.0.0/PKG-INFO

@@ -0,0 +1,624 @@
+Metadata-Version: 2.4
+Name: ecmind-blue-studio
+Version: 1.0.0
+Summary: ECMind blue Studio, admin interface for the ecmind-blue-client
+Author: ECMind GmbH
+Author-email: ECMind GmbH <info@ecmind.ch>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: jinja2
+Requires-Dist: pydantic-settings
+Requires-Dist: itsdangerous
+Requires-Dist: python-multipart
+Requires-Dist: ecmind-blue-client==1.0.1
+Requires-Python: >=3.13
+Project-URL: Homepage, https://ecmind.ch/
+Project-URL: Repository, https://gitlab.ecmind.ch/open/ecmind_blue_studio
+Description-Content-Type: text/markdown
+
+# ECMind blue Studio
+
+A admin interface for the DMS enaio(r) (OPTIMAL SYSTEMS GmbH), exposing the 
+ecmind-blue-client features.
+Query folders, registers and documents with a simple query language in a Monaco 
+editor, inspect results and download files. Works fully offline against your
+DMS infrastructure; all frontend assets are vendored.
+
+## Features (work in progress)
+
+- Browser-like vertical tabs, each with a query editor and a result view
+- Object definition explorer: every cabinet, type and index field with its full
+  configuration, a filter over all of it, prefilled statements per object type
+  and the native asobjdef.xml as download
+- Job call monitor: the live server job stream with filters per server, job,
+  computer, application and user, and the full parameters of a single call with
+  base64 payloads decoded; every value in the detail header filters the stream
+  to itself, and any captured call can be sent to a new tab as a ready to run
+  statement
+- Raw job calls from the editor: `execute krn.GetServerInfo set Flags = 0` runs
+  any server job with typed parameters, input files and its response files
+  previewable and downloadable
+- Simple query language for folders, registers and documents with subqueries,
+  Klausel-style conditions, code completion and diagnostics
+- Batch values: `let id = #UUID7#` names a value for the whole batch and
+  `print @res.Count, @res.TotalHits` shows what a statement answered
+- Security statements for users, groups, roles, membership and the rights export
+- Registry statements that read and write the servers' own configuration, all
+  configured servers at once or one by name, with the server in every row
+- Result tables per object type with file download and a document preview:
+  text formats in a Monaco editor with syntax colouring, find, formatting
+  and copy, PDF and images in the browser's own viewer; a save button turns the
+  edited text into an update statement in a new tab
+- English/German localization with automatic detection
+- Per-login configuration in the DMS: theme, language and saved queries follow
+  the user to any browser, with a storage dialog to inspect, export, import or
+  delete the stored JSON
+
+## Requirements
+
+- Python >= 3.13 and [uv](https://docs.astral.sh/uv/)
+- A DMS application server (default: 127.0.0.1:4000)
+- A technical account with the system role "Kontextwechsel" (switch context)
+
+## Setup
+
+```
+uv sync
+copy .env.example .env
+# edit .env: servers, technical account, session secret
+```
+
+## Run
+
+```
+uv run uvicorn ecmind_blue_studio.main:app --reload --host 127.0.0.1 --port 8099
+```
+
+Then open http://127.0.0.1:8099 and log in with a DMS user.
+
+### Deployment notes
+
+- Keep `.env` private (`chmod 600 .env`): it holds the DMS password and the
+  cookie-signing secret. The session file (`EBS_SESSION_FILE`) is created 0600
+  by the application itself and holds only hashed session ids.
+- Behind TLS, set `EBS_COOKIE_SECURE=true` so the session cookie carries the
+  Secure flag. The login form additionally refuses cross-origin posts: the
+  `Origin` host must match `Host` or `X-Forwarded-Host`, so a reverse proxy
+  must forward one of the two (nginx: `proxy_set_header Host $host;`).
+- `GET /health` is open for liveness probes and names the exact version only
+  to signed-in users. `GET /health/ready` performs throwaway logins and is
+  restricted to localhost by the client address; do not route it through a
+  reverse proxy, where every caller looks local.
+- Spilled response files (answers above `EBS_RESPONSE_SPILL_MB`) land in a
+  0700 directory per service account under the system temp directory and are
+  removed on expiry, logout and shutdown.
+
+## Object definition
+
+The first tab cannot be closed and shows what the DMS server knows about its
+own data model: cabinets with their folders, registers and documents, the index
+mask fields of every type with data type, database column and names in the
+configured languages, and the complete configuration of a single field. The
+filter box searches all of it at once, six buttons per object type open a
+prefilled `select`, `count`, `insert`, `update`, `upsert` or `delete` statement
+in a new tab, and the download button hands out the native `asobjdef.xml`.
+
+It needs the system role "DMS: Supervisor" (18) or "Editor: Starten" (11);
+without one of them the tab is not shown.
+
+## Job calls
+
+The second fixed tab shows the live job stream of the configured servers, the
+same feed the Enterprise Manager displays. Press Listen and every finished job
+appears as one line with its timestamp, computer, user, job name, application
+and file counts; a green check for success, a red warning for a failure, and
+optionally a blue play line when the job starts. Filter by server, by job (a
+popup over every namespace the server offers), by computer, application or user,
+or reduce the stream to failures only. Clicking a line shows the call the way
+the Enterprise Manager prints it, with base64 payloads decoded and XML indented.
+Every value in that header is a link: the job and the server narrow the stream
+itself, the computer, application and user filter the lines already on screen,
+and the last link opens the call in a new tab as a ready to run `execute`
+statement, with every parameter filled in and the user it originally ran for.
+
+It needs the system role "DMS: Supervisor" (18) or "Administrator: Starten" (1).
+The monitor runs on the technical connection, which is why the roles are checked
+on the server and not only in the browser. Job parameters are shown unmasked.
+
+## Query language
+
+Each tab has a Monaco editor with completion, hover and live diagnostics for a
+simple query language (see [SPECS.md](SPECS.md) section 4). Ctrl+Enter runs the
+query, Shift+Alt+F formats it, Alt+N opens a tab and Alt+W closes it. Internal
+field names work without brackets:
+
+```
+select document Invoice, DeliveryNote where Status = 'open' order by InvoiceDate desc limit 100
+select document Invoice in (register Correspondence where Subject = 'Dunning*') where InvoiceNo != ''
+select document Invoice where InvoiceNo != '' and Customer.CustomerNo = 'C-10*'
+select folder Customer contains (document Invoice where Status = 'overdue')
+select folder Customer where Invoice.Status = 'overdue' and Blocked = false
+select document Invoice where Clerk = #USER# and InvoiceDate >= #DATE#-1y6m
+select document Invoice columns InvoiceNo, Amount, Customer.CompanyName
+select document Invoice columns InvoiceNo, {OBJECT_FILESIZE}, {OBJECT_MODIFYTIME}, {OBJECT_DOCPAGECOUNT}
+count document Invoice where Status = 'open'
+```
+
+System fields (`OBJECT_ID`, `OBJECT_LINKS`, `OBJECT_FILESIZE`, `OBJECT_COUNT`,
+`OBJECT_MODIFYUSER` and more, see SPECS.md) work in `where`, `order by` and
+`columns`; document-only fields are rejected on folder and register queries
+with a live editor marker.
+
+The editor also flags object types the signed-in user cannot see, and completion
+notes them in its list. The DMS answers a query on such a type with an empty result
+and no error at all, so the hint is shown before the run. It stays a warning and
+never blocks the query: a type you can see may return no rows as well.
+
+Data statements update, create and delete objects, always with the rights of the
+signed-in user:
+
+```
+update document Invoice 4711 set Status = 'paid'
+update document Invoice 4711, 4712 set Status = 'paid'
+delete document Invoice 6524, 6522 purge
+insert document Invoice into 55 set InvoiceNo = 'R-9' file 'scan.pdf'
+upsert document Invoice into 55 set InvoiceNo = 'R-9', Amount = 12.5 search InvoiceNo
+variant 4711 set Status = 'draft' file 'v2.pdf'
+delete document Invoice where Status = 'void' purge
+insert document Invoice into 55 set InvoiceNo = 'R-9', Positions = (Article = 'A-100', Qty = 5), (Article = 'B-200', Qty = 3)
+update document Invoice 4711 set Positions = (Article = 'A-100', Qty = 7) replacetables
+```
+
+A single `insert`, `update` or `variant` shows what it wrote: the objects are
+read back from the server and rendered as a result table below the
+confirmation, with the usual row actions. A large `update` (more objects than
+one result page) and statement batches keep the plain confirmation, because
+reading every object back costs a roundtrip each.
+
+Table fields take a comma separated list of rows, each row a list of
+`Column = value` pairs. On update and upsert the statement has to say whether
+the rows replace the table (`replacetables`) or extend it (`appendtables`) -
+the mode belongs to the whole statement, so replacing one table and appending
+to another needs two statements. The table popup in a result row carries an
+"Edit table" button that opens a new tab with exactly such a statement, filled
+with the rows currently stored.
+
+Files referenced by `file '...'` are attached to the tab with the paperclip
+button; `file #BROWSE#` instead opens the file dialog every time the statement
+`update` and `delete` also take a list of object ids, and every listed object
+gets its own copy of the file; a failing object does not stop the others, and
+the result lists what was written and what failed. On an id based update the
+`set` clause is optional, so
+`update document Invoice 6523 file 'scan.pdf'` replaces only the file and
+`update document Invoice 6523 file #NULL#` only removes it. Prefilled
+document statements (edit button, object definition page) end with
+`file #BROWSE#` as a reminder; delete the line for metadata-only changes.
+File content can also be written inline, with an optional extension
+after the closing quotes so the DMS knows the file type: `file '''<data>
+</data>'''.xml` stores the text, `file b64'''iVBOR...'''.png` decodes base64
+(line breaks and spaces are ignored), and `file #NULL#` removes the document
+file on an update. Without an extension, text becomes a txt and base64 a bin
+file:
+
+```
+insert document Invoice into 5693
+  set InvoiceNo = 'R-9'
+  file b64'''
+iVBORw0KGgoAAAANSUhEUgAAABAAAAARCAYAAADUryzE...
+  '''.png;
+select document Invoice
+```
+
+`let` names a value for the rest of a batch and `print` shows one row of values,
+which is what makes a batch readable and re-usable:
+
+```
+let id = #UUID7#;
+insert document Invoice into 55 set InvoiceNo = 'R-9', Ident = @id;
+insert document Note into 55 set Text = @id;
+print 'filed as', @id, #DATETIME#
+```
+
+```
+execute dms.GetResultList set Flags = 0, XML = '''<DMSQuery/>''' as res;
+print @res.Count, @res.TotalHits
+```
+
+A declaration also names a file: `let f = #BROWSE#` or an inline block. Such a
+name stands in a `file` clause, of a write statement and of a job call alike, and
+carries the file's attributes as members, so one picked file or one inline block
+reaches several statements and can be read without being carried:
+
+```
+let f = #BROWSE#;
+insert document Invoice into 55 set InvoiceNo = #FILEBASE#, Size = @f.filesize file @f;
+update document Invoice 4711 set Scan = @f.filesha256 file @f
+```
+
+An attachment name stays a plain value on purpose: `'scan.pdf'` already means the
+same file in every statement, so there is nothing to declare.
+
+`#UUID4#` and `#UUID7#` generate an identifier at every use, so an insert gets a
+fresh one and an id list gets one per object; declaring it with `let` is how one
+value reaches several statements. `#UUID7#` is ordered by the millisecond it was
+made in, `#UUID4#` is random. A print takes literals, variables and bindings,
+and `@res.*` prints every member the statement it names reported, which is how
+one finds out what a job really answers. Both statements may stand anywhere in a
+batch, where they render as one line each; on their own they render a one-row
+table that exports like any other result.
+
+Security statements administer the DMS users, groups and roles in the same
+language, again with the rights of the signed-in user, so the server enforces
+the role for configuring the security system:
+
+```
+select user where locked = false order by username limit 100
+select user where group = 'Sales'
+select group where user = #USER#
+insert user KOL set display_name = 'Roland Koller', password = 'Start.2026', change_pwd = true
+add user KOL to group Sales
+export security group Sales, Marketing
+```
+
+`select user KOL` shows one account with every attribute, `count group` the
+number alone, and `delete user KOL forward to MEY` hands the portfolios and
+mails over before the account goes. User and group rows carry the same edit
+button as DMS rows: it opens a new tab with an `update user` or `update group`
+statement holding the current values. The password is never part of it, and
+never part of a result or a log.
+
+#### A rights change is not in effect until it is reloaded
+
+A membership or account write lands in the database at once, but the server
+answers every rights decision from the model it holds in memory. Until that is
+re-read, the change is invisible: a search runs with the old rights, the object
+type the new group grants is simply absent from the answer, and **nothing
+reports an error** -- the hit list is empty and the result document does not
+even mention the type. So the write is done and not yet effective, the way a
+registry write is set and not yet saved:
+
+```
+add user KOL to group Sales reload
+reload security
+reload security on 'srv1'
+```
+
+`reload security` runs `mng.UpdateSecuritySystem`, and a write that ends in
+`reload` runs it for that statement alone. Which to use is a question of how
+many changes there are: the job re-reads the whole model, so twenty writes want
+one reload after them and not twenty. A write without the flag says in its
+result that it is not in effect yet; a batch that changes rights and then
+**reads** warns, naming the statement that reads too early.
+
+The job takes no server parameter, so a single call would land on whichever
+machine the pool picked and leave the rest of a cluster answering from a stale
+model. Both forms therefore address every configured server unless an `on`
+clause names one, and the result carries a line per server. The reload is
+idempotent, so asking a machine that was already current costs a re-read and
+nothing else.
+
+Behind the system role "Administrator: Sicherheitssystem konfigurieren" (4), or
+the two roles the `execute` verb needs, since those can call the job directly
+anyway. The call carries the signed-in user in `$$$SwitchContextUserName$$$`, so
+the server checks as well: a user without role 4 gets `-1040906164` from the job
+itself, verified against 12.0.801.
+
+### Free SQL with DMS names
+
+`sql` passes everything after the verb to the server database, with one
+exception: a `{...}` reference is resolved against the object definition first,
+so a statement can name types and fields instead of `object48` and `feld4`.
+
+```
+sql SELECT {original_filename} FROM {PostDoc} WHERE {Status} = 'done'
+```
+
+goes to the database as `SELECT feld1 FROM object48 WHERE feld4 = 'done'`. The
+tables the statement names decide what a bare field means, and either spelling
+does: `sql SELECT {Status} FROM object48` works too. Where that is not enough,
+name the type: `{PostDoc.Status}`. A SQL alias narrows it as well
+(`p.{Status} ... FROM {PostDoc} p`).
+
+System fields resolve to their own columns (`{OBJECT_CRDATE}` becomes
+`angelegt`), and a table field resolves to its row table, so its rows can be
+joined in:
+
+```
+sql SELECT i.{InvoiceNo}, p.{Qty}
+    FROM {Invoice} i JOIN {Invoice.Positions} p ON p.id = i.id
+```
+
+This is a name substitution and never a rewrite. Only the text inside the braces
+is replaced, and only ever by an identifier out of the definition, so the join,
+the clauses and the literals are exactly what you wrote, and a reference cannot
+smuggle SQL in. Braces inside a string, a quoted identifier or a comment stay
+the database's, and so does anything that is not identifier shaped, which is why
+ODBC escapes such as `{fn concat(a,b)}` still pass through.
+
+Completion offers both spellings side by side, so the physical schema and the DMS
+names are one list: `object48` next to `{PostDoc}`, `feld4` next to
+`{PostDoc.Status}`, and `object48list1` labelled as the table field it holds.
+Either spelling finds both, and each shows what the other one is. Hover tells
+which column a reference stands for, and an unknown name is an editor marker
+rather than a server error. Everything outside the braces is still unvalidated
+and never reformatted.
+
+### Server registry
+
+The enaio registry lives per server machine, so two application servers of one
+pool can disagree about a setting and nothing in the studio used to show that.
+Registry statements read and write it with the **server as a column of every
+row**; leaving the `on` clause out addresses every configured server, which is
+what turns "is this the same everywhere?" into one statement:
+
+```
+select registry
+select registry where path = 'Security\*'
+select registry on 'srv1' where key = 'Services\Fulltext'
+select registry where name = 'HelpURL' order by server
+count  registry where path = 'Services\*'
+```
+
+The columns are `server`, `key`, `name`, `path` and `value`, all of them text,
+with the usual `*` and `?` wildcards. Both path separators work: `Security/*` is
+translated to the backslash the server insists on. An entry whose name ends in
+`Pwd`, `Password` or `Secret` shows `***` and never its value, in a result, an
+export or a log alike; `PwdDecryption` and `PasswordExpirationInterval` are
+settings rather than secrets and stay readable.
+
+A write names one entry by its absolute path, never a wildcard, and reports the
+previous value beside the new one for every server it reached:
+
+```
+update registry on 'srv1' set 'Security\HelpURL' = 'Test'
+update registry create set 'Security\NewEntry' = 'x'
+update registry set 'HelpURL' = 'https://help.example' save
+reload registry on 'srv1'
+```
+
+`krn.RESetRegValue` changes the running server's memory and nothing else, so
+**a write is not persisted unless the statement ends in `save`** - the result
+says so, and `reload registry` throws an unsaved change away right now. A path
+the server does not know is refused unless the statement says `create`, and one
+failing entry does not stop the others. One unreachable server never ends the
+run: it is reported beside the rows the others returned.
+
+There is no delete: the server API has no job that removes a registry entry.
+
+Behind the same system roles as the job call monitor, "DMS: Supervisor" (18) or
+"Administrator: Starten" (1), enforced on the server. Like `execute`, these
+statements run on the technical connection, because the `krn.RE*` jobs have no
+rights model of their own; a read carries the signed-in user into the server's
+job log so it records who looked.
+
+### Server threads and queues
+
+A thread pool belongs to one kernel process, so this is the registry's problem
+again: `krn.JobThreadGetInfo` takes no server parameter, and the pool would
+answer a different machine on every run. So the **server is a column of every
+row** here too, and leaving the `on` clause out asks all of them:
+
+```
+select threads
+select threads where running = true
+select threads where idle = false order by avgjob desc
+select threads on 'srv1' where queue = 'dms'
+select threads where jobname = 'wfm.*' columns queue, number, jobname, username
+count  threads where running = true
+
+select queues
+select queues where jobswaiting > 0
+select queues columns queue, numthreads, priority, jobsposted, namespaces
+```
+
+Unlike the registry's text columns these are **typed**, which is what makes
+`order by avgjob desc` sort numerically and `where start > datetime'...'` mean
+what it looks like. Beside the twenty fields the server reports there are five
+derived ones, because the raw fields do not answer what you actually ask:
+`running` (a job on the thread right now), `idle` (a thread never used),
+`avgjob` (the mean job in milliseconds), and `duration` and `queuewait` for the
+last job, both empty for as long as it is still running.
+
+Two of the server's own fields read differently than the vendor documentation
+suggests, and the studio follows the measurement rather than the document:
+`jobsummary` is the **total** time that thread has ever worked, not the last
+job's runtime, which is why `avgjob` exists; and `sql` is documented but was
+empty on every server probed, so nothing relies on it.
+
+The call stack of one thread reads as the server writes one in its own error
+messages, innermost frame first:
+
+```
+select callstack of thread 4940 on 'srv1'
+```
+
+And one running job can be interrupted:
+
+```
+break thread 4940 on 'srv1'
+break thread 4940 job 1057423 on 'srv1'
+```
+
+**A break is a request, not a result.** The server accepts one for any job and
+only interrupts jobs that support being interrupted, so the statement reads the
+thread again afterwards and says which of the two happened: *stopped*, or
+*accepted and still running*. In a batch the second counts as a failed
+statement. A thread with no job is not asked at all. `on` is required here and
+names exactly one server, because a thread id means nothing on another machine.
+
+Behind the same system roles as the registry family, "DMS: Supervisor" (18) or
+"Administrator: Starten" (1). That gate matters for a plain read: the snapshot
+carries session GUIDs, client station names and the user every job runs as. A
+read carries the signed-in user into the server's job log so it records who
+looked.
+
+### Job calls from the editor
+
+`execute` calls any server job directly, with a typed parameter list:
+
+```
+execute krn.GetServerInfo set Flags = 0, Info = 3
+
+execute dms.GetResultList
+  set Flags = 16,
+    XML = '''<DMSQuery requesttype="LOL" pagesize="10">
+  <Archive>
+    <ObjectType internal_name="Invoice">
+      <Fields field_schema="MIN"/>
+    </ObjectType>
+  </Archive>
+</DMSQuery>''',
+    Encoding = 'UTF-8'
+```
+
+The type of a parameter comes from the literal, so nothing has to be declared:
+`'text'` is a string, `42` an integer, `12.5` a double, `true` a boolean,
+`datetime'...'` a timestamp. A base64 parameter is written **in plain text**
+between `'''` quotes, which is what keeps an XML payload readable in the editor;
+`b64'''...'''` carries real binary. The suffix after a text block names its
+encoding when the job wants something other than UTF-8: `'''...'''.utf16`. Where
+the literal cannot say it, a cast does: `bigint 4294967296`, `string '4711'`.
+
+A job call hands what it answered to the next statement of a batch. `as <name>`
+binds the call, and its members are the output parameters, by their own names,
+next to `returncode`:
+
+```
+// the members of a job call binding are whatever the job answered
+execute krn.SessionLogin set UserName = 'kol', Password = 'secret' as login;
+insert document Note into 4711 set Text = @login.UserGUID
+```
+
+The braces form takes a name no identifier can spell, such as krn.RunScript's
+`$ScriptResult$`: `@run.{$ScriptResult$}`. Nothing declares what a job answers,
+so no type travels with the value: it is made to fit where it lands, text that
+spells a number reaching a number field and a number reaching a text field, and
+only what cannot be converted fails that one statement. Completion offers the
+outputs the reference documents for that job; a name it does not document is a
+warning and still runs, because the server is what decides.
+
+Input files come from the tab's attachments, a `#BROWSE#` pick or inline content,
+the same way a write statement takes them, except that a job takes a list:
+`file 'a.pdf', 'b.pdf'`. Response files are listed under the result with a
+preview for text, PDF and image formats and a download for anything; a text
+file opens in the same editor the result rows use.
+
+The result is the block the job call monitor shows for a call, so the two read
+the same. JSON gives the whole call as one record with text buffers decoded, XML
+gives the raw payload the job returned, and the delimited formats flatten the
+output parameters. A non-zero return code is not an error but the answer: it is
+rendered with the server's own message, exactly as the monitor renders a failed
+call.
+
+Completion knows the jobs the server actually implements: `execute ` offers the
+engines, `execute krn.` their jobs, and picking one writes the whole statement
+with every required parameter and a tab stop on each value. The parameter names,
+types and descriptions come from the enaio Server-API reference, so they are
+documentation rather than gospel: a job the reference has never heard of still
+runs, with a warning and no help.
+
+Unlike every other statement this one does **not** run as the signed-in user. It
+goes out on the pool's own connection, like the job call monitor, because writing
+the caller's identity into the parameter list would aim a job meant for a named
+user at whoever happens to be signed in. A statement that wants a user context
+says so itself:
+
+```
+execute dms.GetResultList
+  set {$$$SwitchContextUserName$$$} = 'administrator',
+      Flags = 16,
+      XML = '''<DMSQuery/>'''
+```
+
+The braces are needed because `$` is not part of a name; the GUID and ID forms
+(`{$$$SwitchContextUserGUID$$$}`, `{$$$SwitchContextUserID$$$}`) work the same
+way. The role gate is therefore the whole access control: "DMS: Supervisor" (18)
+or "Administrator: Starten" (1), checked on the server, not just hidden.
+
+Results render as a table by default or as JSON, JSONL, XML, CSV, TSV or TSV
+quoted, `sql` results included. Every text format opens in an editable editor, so
+the output can be trimmed before copy or download hands it to the next step.
+TSV sanitizes tabs and line breaks inside values to keep one record per line,
+TSV quoted keeps them and quotes like CSV instead. Every result
+row offers details (metadata, variants and versions), an edit button that opens
+a prefilled update statement, file download and, where the format allows it, a
+preview. A text document (txt, log, md, csv, tsv, json, xml, html, svg, yaml,
+ini, sql, js, ts, css, bat, ps1, py) opens in a Monaco editor with the colouring
+of its format, find, a format button for JSON and XML and a copy button for the
+buffer; PDF and images keep the browser's own viewer. The download button always
+hands out the archived file, never what was edited on screen. Text is decoded
+from UTF-8, a BOM, BOM-less UTF-16 or Windows-1252, and a file above
+`EBS_PREVIEW_MAX_BYTES` (20 MB) shows its first bytes and says so.
+
+The save button writes the edited buffer back: the modal closes and a new tab
+opens with the statement prefilled and the caret in it. It never runs by itself
+- the write is the Ctrl+Enter you press.
+
+```
+// PostDoc #4711 (.xml)
+update document PostDoc 4711
+  file '''<Root>
+  <Line>edited</Line>
+</Root>'''.xml
+```
+
+No `set` clause, so a save touches the file and no index field. A comment line
+above the statement explains anything the shape does not say by itself: a text
+block goes out as UTF-8, so a file stored as Windows-1252 or UTF-16 comes back
+re-encoded; a text carrying `'''`, which a text block has no escape for, goes out
+as base64 instead; and a text too long for `EBS_QUERY_MAX_CHARS` is attached to
+the new tab as a file, with the statement naming it. A preview cut short by
+`EBS_PREVIEW_MAX_BYTES` cannot be saved at all - the button is disabled and says
+why, because writing a prefix back would overwrite the document with part of
+itself. Response files of an `execute` run have no object to update, so they have
+no save button.
+
+Statement batches (separated by `;`) stream their results statement by
+statement, report the executed command and the upsert action per row, and can
+be cancelled mid run; the stop button in the toolbar also aborts long running
+queries. A query starting with a comment line names its tab, the question
+button in the toolbar lists all keyboard shortcuts, the info button next to it
+opens the about dialog, and the tab rail shows the connected DMS servers
+above the user menu.
+
+## Per-login configuration
+
+Theme, language, table lines and saved queries live in one JSON document in the
+DMS, in the user data record `ecmind_blue_studio` of the signed-in user (slot
+`EBS_USERDATA_SLOT`, default 80). They are not kept in the browser, so a second
+machine shows the same setup, and a browser reset loses nothing. If the DMS
+refuses user data for a login, the app runs on the defaults and every write is
+blocked with an error rather than falling back to storage that can vanish.
+
+"Settings storage" in the user menu shows the stored document in an editor and
+can download it, load a JSON file into the editor, save manual changes or delete
+the whole record from the DMS.
+
+Open tabs are the exception: they stay in browser storage, shared by all windows
+of the browser, so closing and reopening the browser brings back the last set of
+queries. Which tab is in front stays per window.
+
+## Tests
+
+```
+uv run pytest                            # unit and endpoint tests
+$env:EBS_LIVE_TESTS = "1"; uv run pytest -m live   # against a local DMS (PowerShell)
+```
+
+## Documentation
+
+- [SPECS.md](SPECS.md) - full specification and decision log
+- [TODO.md](TODO.md) - backlog
+- [CHANGELOG.md](CHANGELOG.md) - notable changes
+
+## License
+
+MIT, see [LICENSE](LICENSE). Bundled third-party libraries, fonts, icons and tools are
+acknowledged in [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).
+
+The MIT license covers this software only and grants no rights to the DMS itself. Operators must
+make sure their use of the DMS is covered by their own license agreement with the DMS vendor or
+reseller. See the DMS licensing section of
+[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).