diff --git a/docs/openedx_content/decisions/0005-serving-static-assets.rst b/docs/openedx_content/decisions/0005-serving-static-assets.rst
index c2b01ff43..315f504f9 100644
--- a/docs/openedx_content/decisions/0005-serving-static-assets.rst
+++ b/docs/openedx_content/decisions/0005-serving-static-assets.rst
@@ -6,12 +6,12 @@
 Status
 ------
 
-Accepted in principle. Pending implementation.
+Accepted in principle. Partially implemented. Substantially revised in September 2026.
 
 Context
 --------
 
-Both Studio and the LMS need to serve course team authored static assets as part of the authoring and learning experiences. "Static assets" in the edx-platform context presently refers to: image files, audio files, text document files like PDFs, older video transcript files, and even JavaScript and Python files. It does NOT typically include video files, which are treated separately because of their large file size and complex workflows (processing for multiple resolutions, using third-party dictation services, etc.)
+The Open edX platform needs to serve course team authored static assets as part of the authoring and learning experiences. "Static assets" in the openedx-platform context presently refers to: image files, audio files, text document files like PDFs, older video transcript files, and even JavaScript and Python files. It does NOT typically include video files, which are treated separately because of their large file size and complex workflows (processing for multiple resolutions, using third-party dictation services, attached subtitle files, etc.)
 
 This ADR is the synthesis of various ideas that were discussed across a handful of pull requests and issues. These links are provided for extra context, but they are not required to understand this ADR:
 
@@ -19,20 +19,23 @@ This ADR is the synthesis of various ideas that were discussed across a handful
 * `File Uploads + media_server app #33 <https://github.com/openedx/openedx-learning/pull/33>`_
 * `Modeling Files and File Dependencies #70 <https://github.com/openedx/openedx-learning/issues/70>`_
 * `Serving static assets (disorganized thoughts) #108 <https://github.com/openedx/openedx-learning/issues/108>`_
+* `Unrestricted image upload leads to stored XSS <https://github.com/openedx/openedx-platform/security/advisories/GHSA-c6xg-fh3c-vvhh>`_
 
 Data Storage Implementation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The underlying data models live in the openedx-learning repo. The most relevant models are:
+The underlying data models live in the ``openedx_content`` app. The most relevant models are:
 
-* `Content in contents/models.py <https://github.com/openedx/openedx-learning/blob/main/openedx_learning/core/contents/models.py>`_
-* `Component and ComponentVersion in components/models.py <https://github.com/openedx/openedx-learning/blob/main/openedx_learning/core/components/models.py>`_
+* `Media in media/models.py <https://github.com/openedx/openedx-core/blob/main/src/openedx_content/applets/media/models.py>`_
+* `Component and ComponentVersion in components/models.py <https://github.com/openedx/openedx-core/blob/main/src/openedx_content/applets/components/models.py>`_
 
 Key takeaways about how this data is stored:
 
-* Assets are associated and versioned with Components, where a Component is typically an XBlock. So you don't ask for "version 5 of /static/fig1.webp", you ask for "the /static/fig1.webp associated with version 5 of this block".
-* This initial MVP would be to serve assets for v2 content libraries, where all static assets are associated with a particular component XBlock. Later on, we'll want to allow courses to port their existing files and uploads into this system in a backwards compatible way. We will probably do this by creating a non-XBlock, filesystem Component type that can treat the entire course's uploads as a Component. The specifics for how that is modeled on the backend are out of scope for this ADR, but this general approach is meant to work for both use cases.
-* The actual raw asset data is stored in django-storages using its hash value as the file name. This makes it cheap to make many references to the same asset data under different names and versions, but it means that we cannot simply give direct links to the raw file data to the browser (see the next section for details).
+Currently, all assets are associated and versioned with Components, where a Component is typically an XBlock. So you don't ask for "version 5 of /static/fig1.webp"; you ask for "the /static/fig1.webp associated with version 5 of this Component".
+
+:ref:`openedx-content-adr-0013` proposes a special type of component that only holds assets (an "AssetSet"), and no XBlock, so that a course's existing files and uploads can be referenced by multiple XBlocks or used independently (e.g. a PDF download).
+
+The actual raw asset data is stored in django-storages using its hash value as the file name. This makes it cheap to make many references to the same asset data under different names and versions, but it means that we cannot simply give direct links to the raw file data to the browser (see the next section for details).
 
 The Difficulty with Direct Links to Raw Data Files
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -61,16 +64,23 @@ Application Requirements
 Security Requirements
 ~~~~~~~~~~~~~~~~~~~~~
 
-**Assets must enforce user+file read permissions at the Learning Context level.**
-  The MongoDB GridFS backed ContentStore currently supports course-level access checks that can be toggled on and off for individual assets. Uploaded assets are public by default, and can be downloaded by anyone who knows the URL, regardless of whether or not they are enrolled in the course. They can optionally be "locked", which will restrict downloads to students who are enrolled in the course.
+**The ``openedx_content`` app only knows about LearningPackages and content, not Learning Contexts**
+  Permissions in the Open edX platform are (now) defined by the ``openedx-authz`` authorization framework, and depend on various factors like which learning context (course/library) hosts the asset and what roles the requesting user has. However, this ``openedx_content`` app is a low-level content management system, and does not know about ``openedx-authz`` nor have any way to directly check permissions/authorization.
+
+**Assets require fine-grained permissions.**
+  The Open edX platform today depends on various rules for determining who can access each asset file. The MongoDB GridFS backed ContentStore currently supports course-level access checks that can be toggled on and off for individual assets. Uploaded assets are public by default, but can optionally be "locked", which will restrict downloads to students who are enrolled in the course. Components in courses have complex authorization rules (release dates, cohorts, A/B testing, etc.), so any assets that are attached to Components should also respect those same rules. In other words, *permissions checking must be extensible*. The ``openedx_content`` app will implement the details of how to serve an asset, but it will not have the necessary models and logic to determine whether it is allowed to.
+
+**Uploaded assets must never execute scripts with the LMS or Studio origin.**
+  A user navigating to an asset URL, or a page framing it, must not result in author-supplied script running with the session cookies of the LMS or Studio.
+
+  Any asset that a browser will render as a *document* (HTML, SVG, XML, and to a lesser extent PDF) can carry script. If such a file is served inline from the LMS or Studio origin, and a user navigates to it or a page embeds it in an ``<iframe>``, that script runs with the origin's cookies and can call any same-origin API on the victim's behalf. `GHSA-c6xg-fh3c-vvhh <https://github.com/openedx/openedx-platform/security/advisories/GHSA-c6xg-fh3c-vvhh>`_ (September 2026, rated Critical) reported exactly this against the legacy contentstore. Studio stored the uploader's declared MIME type verbatim, and the LMS served the file inline with that type and no neutralizing headers. A course author could upload an HTML file disguised as an image, and any global-staff user who opened the link would be scripted against the Studio session, including the same-origin Django admin, allowing privilege escalation to superuser.
 
-**Assets should enforce more granular permissions at the individual Component level.**
-  An important distinction between ContentStore and v2 Content Library assets is that the latter can be directly associated with a Component. As a long term goal, we should be able to make permissions check on per-Component basis. So if a student does not have permission to view a Component for whatever reason (wrong content group, exam hasn't started, etc.), then they should also not have permission to see static assets associated with that component.
+  Note what this requirement does *not* cover. A page that deliberately loads an uploaded file as a subresource (``<script src>``, ``<link rel=stylesheet>``) executes it with the page's own origin no matter where the file is served from. That is a content authoring concern (the same one raised by HTML XBlocks that contain script), not an asset serving concern, and no serving-side measure, including a separate domain, changes it.
 
-  The further implication of this requirement is that *permissions checking must be extensible*. The openedx-learning repo will implement the details of how to serve an asset, but it will not have the necessary models and logic to determine whether it is allowed to.
+  Note: the Open edX platform already allows authors to put arbitrary HTML in their course content, including scripts, so reproducing the privilege escalation exploit of that security advisory is trivial, without any need to involve static assets at all. However, there is a long-term goal of eliminating such risks from the platform entirely, so we definitely want to close down any such risks in the way static assets are served.
 
-**Assets must be served from an entirely different domain than the LMS and Studio instances.**
-  To reduce our chance of maliciously uploaded JavaScript compromising LMS and Studio users, user-uploaded assets must live on an entirely different domain from LMS and Studio (i.e. not just another subdomain). So if our LMS is located at ``sandbox.openedx.org``, the files should be accessed at a URL like ``assets.sandbox.openedx.io``.
+**The serving layer, not the uploader, decides the Content-Type.**
+  The MIME type recorded at upload time is a hint. The response's ``Content-Type`` must come from an allowlist of types that are safe to serve inline (raster images, audio, video, fonts, CSS, JavaScript, JSON, plain text, PDF, and SVG and HTML only because they are sandboxed). Anything else is served as ``application/octet-stream`` with ``Content-Disposition: attachment``, and every response carries ``X-Content-Type-Options: nosniff`` so a browser cannot sniff an "image" into HTML.
 
 Operational Requirements
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -81,17 +91,20 @@ Operational Requirements
 **Serving assets should not *require* ASGI deployment.**
   Deploying the LMS and Studio using ASGI would likely substantially improve the scalability of a Django-based streaming solution, but migrating and testing this new deployment type for the entire stack is a large task and is considered out of scope for this project.
 
+**Serving assets must not require operators to provision additional domains.**
+  Tutor, the supported deployment method, places the LMS, Studio and the MFEs under a single base domain and manages certificates for them. A design that only becomes secure once an operator buys and configures a second registrable domain would leave most sites running the insecure configuration.
+
 Decision
 --------
 
 URLs
 ~~~~
 
-The format will be: ``https://{asset_server}/assets/apps/{app}/{learning_package_key}/{component_key}/{version}/{filepath}``
+Assets are served from the LMS and Studio hosts themselves. There is no separate asset host.
 
-The assets will be served from a completely different domain from the LMS and Studio, and will not be a subdomain.
+The format will be: ``https://{lms_or_studio_host}/...{context}.../{component_key}/{version}/{filepath}``
 
-A more concrete example: ``https://studio.assets.sandbox.openedx.io/apps/content_libraries/lib:Axim:200/xblock.v1:problem@826eb471-0db2-4943-b343-afa65a6fdeb5/v2/static/images/fig1.png``
+A more concrete example: ``https://demo.openedx.org/assets/content_libraries/lib:Axim:200/xblock.v1:problem@multi_choice_8/v4/static/images/fig1.png``
 
 The ``version`` can be:
 
@@ -99,63 +112,103 @@ The ``version`` can be:
 * ``published`` indicating the latest published version (viewed by students in the LMS)
 * ``v{num}`` meaning a specific version–e.g. ``v20`` for version 20.
 
-Asset Server Implementation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Response Headers
+~~~~~~~~~~~~~~~~
 
-There will be two asset server URLs–one corresponding to the LMS and one corresponding to Studio, each with their own subdomain. An example set of domains might be:
+Every asset response, whether it succeeds or fails, carries:
 
-* LMS: ``sandbox.openedx.org``
-* Studio: ``studio.sandbox.openedx.org``
-* LMS Assets: ``lms.assets.sandbox.openedx.io`` (note the ``.io`` top level domain)
-* Studio Assets: ``studio.assets.sandbox.openedx.io``
+* ``Content-Security-Policy: sandbox``
+* ``X-Content-Type-Options: nosniff``
 
-The asset serving domains will be serviced by a Caddy instance that is configured as a reverse proxy to the LMS or Studio. Caddy will be configured to only proxy a specific set of paths that correspond to valid asset URLs.
+``sandbox`` is a *document* directive. It has no effect on subresource loads, so ``<img>``, ``<script src>``, ``<link>``, ``<audio>``, ``<video>``, fonts and ``fetch()`` continue to work exactly as before. It takes effect only when the asset is loaded as a document: a top-level navigation to the asset URL, or an ``<iframe>``, ``<object>`` or ``<embed>``. In those cases the document gets an opaque origin and scripting is disabled, so an uploaded HTML or SVG file renders but cannot read cookies, cannot set cookies on the parent domain, and cannot make credentialed same-origin requests. Django's CSRF check additionally rejects the ``null`` ``Origin`` such a document would send.
 
-Django View Implemenation
-~~~~~~~~~~~~~~~~~~~~~~~~~
+This is the same policy the upstream contentserver now applies, so a course whose ``/static/`` files migrate from contentstore to ``openedx_content`` (per :ref:`openedx-content-adr-0013`) sees no change in behaviour.
 
-The LMS and Studio will each have one or two apps that implement view endpoints by extending a view that will be provided by the Learning Core. These views will only respond to requests that come via the asset domains (i.e. they will not work if you request the same paths using the LMS or Studio domains).
+``Content-Type`` is chosen by the serving code from the allowlist described in the security requirements, using the stored media type and file extension as inputs. Types outside the allowlist are served as ``application/octet-stream`` with ``Content-Disposition: attachment; filename="..."``, using the asset's path within the component for the filename.
+
+**"Insecure Legacy Assets"**: The relaxed form ``sandbox allow-scripts allow-forms allow-popups`` would keep the opaque origin while letting scripts run, which would preserve the legacy pattern of iframing an uploaded HTML5 interactive from an HTML block. It is not adopted here. Its safety depends on the site's cookies being ``SameSite=Lax`` or stricter, but `the platform defaults to SameSite=None <https://github.com/openedx/openedx-platform/blob/aa5ec07c61a90ca4ef0ae05eebddc653e5d4e033/lms/envs/production.py#L140>`_. Any per-asset relaxation is left to a future decision, and would be a platform-level flag in the spirit of ``course_assets.allow_unsafe_asset_rendering``, passed into the ``openedx_content`` serving API rather than decided by it.
+
+Reverse Proxy Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Django is poorly suited to serving large static assets, particularly when deployed using WSGI. Instead of streaming the actual file data, the Django views serving assets will make use of the ``X-Accel-Redirect`` header. This header is supported by both Caddy and Nginx, and will cause them to fetch the data from the specified URI to send to the user. This redirect happens internally in the proxy and does *not* change the browser address. For sites using an object store like S3, the Django view will generate and send a signed URL to the asset. For sites using file-based Django media storage, the view will send a URL that Caddy or Nginx knows how to load from the file system.
 
-The Django view will also be responsible for setting other important header information, such as size, content type, and caching information.
+The proxy that fronts the LMS and Studio (Caddy in Tutor) handles the internal redirect for the ``/assets/`` path prefix. It is a hard requirement that the proxy configuration for that internal location **forces** ``Content-Security-Policy: sandbox`` and ``X-Content-Type-Options: nosniff`` itself, and does not rely on them being copied from the Django response. Proxies generally carry only a fixed set of headers (such as ``Content-Type``, ``Content-Disposition`` and ``Cache-Control``) from the Django response across an ``X-Accel-Redirect`` and take the rest from the redirect target, so a security header set only by the view can silently disappear. The reference Tutor configuration and any deployment documentation must state this, and the test suite must include a request that goes through the proxy, not only through the Django test client.
+
+Until a deployment has the proxy configured, a Django-streamed fallback (as the interim Studio endpoints do today) is acceptable for low-traffic use, provided it sets the same headers in the view. This same mechanism can be used to serve "Insecure Legacy Assets", if required on a per-asset basis.
+
+Django View Implementations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``openedx_content`` provides an API that, given a component version and asset path, returns an ``HttpResponse`` with the ``X-Accel-Redirect`` header and all of the required metadata headers (content type, sandbox, nosniff, disposition, ETag, caching, and the ``X-Open-edX-*`` informational headers). It never enforces permissions nor returns ``401`` or ``403``; it does not know who is asking (see next decision).
 
 Permissions
 ~~~~~~~~~~~
 
-The Learning Core provided view will contain the logic for looking up and serving assets, but it will be the responsibility of an app in Studio or the LMS to extend it with permissions checking logic. This logic may vary from app to app. For instance, Studio would likely implement a simple permissions checking model that only examines the learning context and restricts access to course staff. LMS might eventually use a much more sophisticated model that looks at the individual Component that an asset belongs to.
+The ``openedx_content`` API contains the logic for looking up and serving assets, but it is the responsibility of an app in Studio or the LMS to wrap it with permissions checking logic using ``openedx-authz``. This logic may vary from app to app. For instance, Studio would likely implement a simple permissions checking model that only examines the learning context and restricts access to course staff. LMS might eventually use a much more sophisticated model that looks at the individual Component that an asset belongs to, and which prohibits access to any version other than the current published version.
 
-Cookie Authentication
-~~~~~~~~~~~~~~~~~~~~~
+Authentication
+~~~~~~~~~~~~~~
 
-Authentication will use a session cookie for each asset server domain.
+Because assets are served from the same origin as the LMS and Studio REST API, requests carry the ordinary session cookie and no additional login flow is needed. Pages do not need to do anything special before loading assets.
 
 Assets that are publicly readable will not require authentication.
 
 Asset requests may return a 403 error if the user is logged in but not authorized to download the asset. They will return a 401 error for users that are not authenticated.
 
-There will be a new endpoint exposed in LMS/Studio that will force a redirect and login to the asset server. Pages that make use of assets will be expected to load that endpoint in their ``<head>`` before any page assets are loaded. The flow would go like this:
+Masquerading works the same way it does for any other LMS view, since it is the same session. Whether a masqueraded request is evaluated against the masqueraded user's permissions is a decision for the platform app's permission check, not for ``openedx_content``.
+
+Rejected Alternatives
+---------------------
+
+Checking Permissions Within ``openedx_content`` Itself
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-#. There is a ``<script>`` tag that points to a new check-login endpoint in LMS/Studio, causing the browser to load and execute it before images are loaded.
-#. This LMS/Studio endpoint generates a random token, stores user information in its backend cache based on that token, and redirects the user to an asset server login endpoint using that token as a querystring parameter.
-#. The asset server endpoint checks the cache with that token for the relevant user information, logs that user in, and removes the cache entry. It has access to the cache because it's still proxying to the same LMS/Studio process underneath–it's just being called from a different domain.
+At the time of this ADR, ``openedx_content`` does not (yet) have a table that maps each :class:`LearningPackage` to its corresponding learning context, and ``openedx_content`` is thus unaware of the user-visible identifier (``course-v1:...`` for courses, ``lib:...`` for libraries, etc.) for each Learning Package. Since permissions are currently defined within the ``openedx-authz`` system based on these identifier strings, and since no part of ``openedx-core`` yet interacts with the ``authz`` system, we have proposed the design described above.
 
-Masquerading
-~~~~~~~~~~~~
+On the other hand, if were to add a dependency on ``openedx-authz`` to ``openedx-core`` and to either:
 
-We could theoretically take masquerading into account during the auto-login process for the asset server, but we would not implement it in the first iteration.
+* change authoring permissions so that ``authz`` rules define them on a per-LearningPackage basis, not on a per-context basis; or
+* add a table to ``openedx_content`` that maps each :class:`LearningPackage` to at most one learning context identifier (``course-v1:...`` for courses, ``lib:...`` for libraries, etc.),
 
-Rejected Alternatives
----------------------
+then we could have a single REST API for serving assets implemented by the ``openedx_content`` app itself, rather than providing a low-level API that gets combined with authorization code and integrated into various higher-level REST APIs.
 
-Per-asset Login Redirection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+In the first option (permissions are based on LearningPackage), it would also be necessary to associate each :class:`LearningPackage` with an organization, to support org-based permissions.
+
+A disadvantage of this approach is that even though ``openedx_content`` would have basic context about each static asset file, it wouldn't have enough information to allow ``authz`` to enforce fine-grained access control, such as anything based on cohort, release dates, A/B testing, or other high-level features, as only the LMS has enough context for that.
+
+Serving Assets from a Separate Domain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The original version of this ADR required that assets be served from an entirely different registrable domain from the LMS and Studio (for example ``lms.assets.sandbox.openedx-assets.io`` for an LMS at ``learning.openedx.org``), so that script in an uploaded file could never run with the LMS or Studio origin. A distinct subdomain was explicitly ruled out because Open edX scopes its session and JWT cookies to the parent domain, so every subdomain receives them.
+
+The threat is real, as `this advisory <https://github.com/openedx/openedx-platform/security/advisories/GHSA-c6xg-fh3c-vvhh>`_ demonstrates, but the separate domain is not the right remedy for this platform:
+
+* It required every operator to purchase and manage a second domain and certificate, which Tutor does not support out of the box. Sites that did not do so would have had no protection at all.
+* Because cookies do not cross domains, the design needed a token-based cross-domain authorization flow: a check-login ``<script>`` in the ``<head>`` of every page that shows non-public assets, a cache-backed one-time token, a second session on the asset domain, and unsolved masquerading. All of that machinery, and the per-asset login redirection variant that was rejected alongside it, disappears once assets are same-origin.
+* Cross-origin assets also required CORS for fonts, ES modules, canvas reads and ``fetch()``.
+* It was not sufficient on its own. The asset domain had its own session, so an unsandboxed uploaded HTML file navigated to on that domain could still read and exfiltrate every other draft or locked asset the victim could access there. The ``sandbox`` CSP header was needed anyway, and once present its neutralizes the same-origin attack too.
+
+The one residual benefit of an isolated domain is that a per-course "allow unsafe rendering" escape hatch would expose only the asset domain's session rather than the whole platform. That was judged not worth the operational cost. Operators who want that isolation can still front the ``/assets/`` path with a different hostname at the proxy layer, but this ADR does not design for it and the authentication flow that a *different site* would need is not provided.
+
+Serving Everything as an Attachment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sending ``Content-Disposition: attachment`` on every asset would also prevent uploaded HTML and SVG from rendering, because browsers apply it to navigation and frames but ignore it for subresource loads. It was rejected as the primary defense because course teams legitimately link learners to PDFs and images to view in the browser, and frame uploaded HTML from HTML blocks. ``sandbox`` neutralizes the content while still letting it render. ``attachment`` is retained only for types outside the inline allowlist.
+
+Validating Content at Upload Time as the Only Defense
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Rejecting HTML and SVG uploads, or sniffing file contents at upload, was rejected as the sole measure. Polyglot files defeat sniffing, large amounts of already-uploaded content would remain unprotected, and restrictions at the serving layer are more comprehensive. Stricter upload validation in the platform is welcome as defense in depth, and is still worth implementing, either as an API within ``openedx_content`` or in other layers of the platform, but is left out of scope for this ADR.
+
+Changelog
+---------
+
+2026-09-18:
 
-It is possible to initiate a series of redirects for every unauthenticated request to a non-public asset. This remove the need for pages using assets to have to include this special handling in their ``<head>``. Some drawbacks of this approach:
+* Major revisions to every section. Added `sandbox` header and removed plan for serving from separate domain. Clarified many security requirements. Clarified separation of concerns around authentication. Planned for combining LMS & Studio domains together in the future.
 
-* Injecting tokens in the querystrings of assets may cause errors or security leaks.
-* Combining per-asset redirection with dedicated endpoints for the tokens would mean even more redirection, increasing the number of places where things could fail.
-* There is a greater risk of bugs causing infinite loops.
-* A page that loads many assets concurrently may trigger a large set of duplicated redirects/logins.
+2023-12-04:
 
-Forcing the page to opt into asset authentication is unusual and may cause bugs. But the hope is that it is operationally safer and simpler, and that the number of views that directly render non-public assets will be relatively small.
+* Initial version
+  
\ No newline at end of file
diff --git a/docs/openedx_content/decisions/0013-course-static-assets.rst b/docs/openedx_content/decisions/0013-course-static-assets.rst
new file mode 100644
index 000000000..aee63cd96
--- /dev/null
+++ b/docs/openedx_content/decisions/0013-course-static-assets.rst
@@ -0,0 +1,96 @@
+.. _openedx-content-adr-0013:
+
+13. Course Static Assets as "Upload" Components
+===============================================
+
+Status
+------
+
+Draft. Depends on :ref:`openedx-content-adr-0012` and :ref:`openedx-content-adr-0005`.
+
+Context
+-------
+
+Today, a course's "Files & Uploads" live in the legacy MongoDB contentstore, as a flat, course-wide namespace of paths that OLX references as ``/static/{path}``. As a first step in migrating all content away from MongoDB, we need to define how to store such files in ``openedx_content`` (within a :class:`LearningPackage`).
+
+:ref:`openedx-content-adr-0005` anticipates the shape of the answer when it refers to a special type of component that only holds assets and no XBlock, and the :class:`ComponentType` docstring mentions "a component type to represent packages of files for things like Files and Uploads". `openedx-learning issue #70 <https://github.com/openedx/openedx-learning/issues/70>`_ independently proposed folders as a component type, with relative references resolving within a folder and its subdirectories.
+
+Two properties of the existing schema shape the details:
+
+- :class:`ComponentVersionMedia` is a full snapshot of a component version's media, not a delta. Every new version of a component rewrites one row per media item it holds.
+- ``component_code`` is a ``code_field``, which forbids slashes and restricts characters to ``[\w.-]``, whereas the ``key`` on :class:`ComponentVersionMedia` is a ``ref_field``: 500 characters and opaque, so slashes are fine.
+
+Decisions
+---------
+
+1. An "Upload" is a new :class:`Component` type that holds one or more asset files.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In both courses and libraries, shared/reusable assets (referenced by multiple components, or uploaded directly to a library and not to a particular component) will live in the learning package as a new non-XBlock Component type, "Upload". This requires no schema change.
+
+The type is a :class:`ComponentType` with namespace ``openedx.v1`` and name ``upload``.
+
+An upload is technically most like a folder, and our preliminary thinking about this idea also used the terms "AssetSet" or "Folder" for what we are naming an "Upload" in this ADR. "Upload" is chosen because it matches the "Uploads" part of the "Files & Uploads" page in the Studio UI, implies a generally singular thing without ruling out multiple files, doesn't conflict with any other names used in the platform, and is hopefully fairly self-evident to users, unlike a technical term like "AssetSet".
+
+2. Uploads group related files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Uploads are anticipated to often contain only a single file. Grouping multiple files together into an Upload is supported but meant mostly for files that have a technical relationship to each other:
+
+* Different resolutions of a single image file;
+* Different video encodings and associated subtitle files;
+* An HTML file and its associated CSS/JS/PNG resources; etc.
+
+Grouping files together into a single ``Upload`` for organizational purposes only (e.g. "Images used in the course intro") is not recommended; ``Collection`` and tags are available for those purposes, as well as attaching files directly to the ``Component`` where they are referenced, rather than creating a separate ``Upload`` Component.
+
+3. Uploads support relative links
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Within a single "Upload", files can use relative references to each other. For example, an HTML file can reference "./image.jpeg" which would be rendered if the HTML file was viewed in the browser and the image in question was part of the same ``Upload`` component.
+
+4. Course "Files & Uploads" assets are "Upload"-type Components within the run's learning package
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For courses authored in the future, we want to encourage most static assets to be directly attached to the Component where they are used. But shared assets (referenced by multiple components), including every "Files & Uploads" asset migrated from legacy MongoDB storage, will live in the run's learning package as Uploads.
+
+5. One Upload per existing "Files & Uploads" asset
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When migrating assets from MongoDB/contentstore to ``openedx_content``, each asset in "Files & Uploads" will become one ``Upload`` component in the LearningPackage. It would be nice to automatically group related files together, but this is likely not worth the effort it would require.
+
+6. Identifiers
+~~~~~~~~~~~~~~
+
+All Uploads (in fact, all PublishableEntities) have a mutable ``title`` which can be used to store a human-readable name for the entity, such as "Illustration of the Moon's Orbit (SVG)".
+
+``component_code`` must be unique and is restricted in what special characters can be used, so ideally should be set to a slugified version of the title of the asset during initial upload, e.g. ``moon-orbit-illustration``.
+
+:class:`ComponentVersionMedia` continues to hold the full path and filename of each asset.
+
+7. Assets are not part of the learner-facing outline
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Upload components are not children of the course container or any of its descendants. Putting them there would mean every asset upload creates a new version of an outline container.
+
+8. Uploads cannot be referenced without an ``UploadUsageLink``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+TODO: write this up
+
+9. Per-asset metadata stays in openedx-platform
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``locked`` flag, ``displayname``, thumbnails and import paths that the legacy contentstore carries are not modelled here. :ref:`openedx-content-adr-0005` already makes permission checking the platform's responsibility, so a platform-side model keyed by run and path is the right home. The Upload stays a dumb mapping of paths to :class:`Media`.
+
+Rejected Alternatives
+---------------------
+
+One Upload component per course run
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Treating the whole course's uploads as a single component is the simplest model, and is simpler to migrate to from contentstore's flat namespace. Rejected because :class:`ComponentVersionMedia` is a snapshot, so a single course-wide Upload would rewrite one row per asset on every upload. For a course with 5,000 assets, that would require updating 5,000 rows per upload, which is incredibly inefficient. Further, this big volume of data cannot be pruned while any draft or published version still references it.
+
+The name "Folder" instead of "Upload"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Folder would be more accurate, but implies using "Upload" as an organizational tool, whereas we want to encourage authors to think of each Upload component as a singular thing (an Image, a PDF, an HTML interactive, a Video), regardless of how many files it technically consists of.